[VSC-1814] Serial usb adapter doesn't clear (#1725)

radurentea · web-flow · commit 52bb368a140c · 2025-12-19T17:43:39.000+08:00
* fix: persist adapter serial

- Parse and persist OpenOCD USB-JTAG adapter serial in extension workspace state.
- Clear stored serial when changing target to avoid stale device selection.
- Add toggleable [Adapter] S:&lt;serial&gt; L:&lt;location&gt; status bar item (highest priority) and expose it in ESP-IDF Explorer.
- Add translations and document the new command.

* fix: clear adapter binding

 - stop OpenOCD on config select/switch

* fix(statusbar): refresh adapter item on idf.customExtraVars changes

* fix: lint

* Update status bar item name and action

* fix: lint

* Add validation logic to block flash JTAG for edge case

- In case no usb adapter location/serial is set and multiple boards are connected, make user to select a target.

* Add silent mode for ESP Detect Config (used by JTAG guard)
diff --git a/docs_espressif/en/commands.rst b/docs_espressif/en/commands.rst
@@ -94,6 +94,8 @@ All commands start with ``ESP-IDF:``.
      - Launch UI to create a CSV file for `ESP-IDF Non-Volatile Storage Library <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_flash.html>`_.
    * - Open ESP-IDF Terminal
      - Open a terminal with IDF_PATH and Python virtual environment activated.
+   * - OpenOCD Adaptor (serial & location)
+     - Toggle the status bar item that shows the OpenOCD adapter serial number (S) and USB adapter location (L), useful to verify which adapter will be used when multiple devices are connected.
    * - Partition Table Editor
      - Launch UI to manage custom partition table as described in `ESP-IDF Partition Tables <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html>`_.
    * - Pick a Workspace Folder
diff --git a/docs_espressif/zh_CN/commands.rst b/docs_espressif/zh_CN/commands.rst
@@ -94,6 +94,8 @@
      - 启动 UI，创建 `ESP-IDF 非易失性存储库 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-reference/storage/nvs_flash.html>`_ 的 CSV 文件。
    * - 打开 ESP-IDF 终端
      - 打开一个终端，并激活 IDF_PATH 和 Python 虚拟环境。
+   * - OpenOCD 适配器状态栏
+     - 切换状态栏显示 OpenOCD 适配器序列号（S）和 USB 适配器位置（L），用于在连接多个设备时确认将使用的适配器。
    * - 分区表编辑器
      - 启动 UI，如 `ESP-IDF 分区表 <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/partition-tables.html>`_ 中所述，管理自定义分区表。
    * - 选择工作区文件夹
diff --git a/l10n/bundle.l10n.es.json b/l10n/bundle.l10n.es.json
@@ -28,6 +28,9 @@
   "Show notifications but do not focus tasks output.": "Muestra notificaciones pero no centras el resultado de las tareas.",
   "Do not show notifications but focus tasks output.": "No muestre notificaciones, pero centre la salida de las tareas.",
   "Show notifications and focus tasks output.": "Muestra notificaciones y resultados de tareas de enfoque.",
+  "OpenOCD Adaptor (serial & location)": "Adaptador OpenOCD (serie y ubicación)",
+  "Set Target": "Establecer objetivo",
+  "Multiple connected boards were detected, but no OpenOCD adapter is selected (serial/location). To avoid flashing the wrong device, set the target for the connected board and rebuild.": "Se detectaron varias placas conectadas, pero no se ha seleccionado ningún adaptador OpenOCD (serie/ubicación). Para evitar flashear el dispositivo incorrecto, establezca el objetivo de la placa conectada y vuelva a compilar.",
   "Select the output and notification mode": "Seleccione el modo de salida y notificación",
   "Notification mode has changed to {mode}": "El modo de notificación ha cambiado a {mode}",
   "No project configuration found": "No se encontró ninguna configuración de proyecto",
diff --git a/l10n/bundle.l10n.pt.json b/l10n/bundle.l10n.pt.json
@@ -28,6 +28,9 @@
   "Show notifications but do not focus tasks output.": "Mostre notificações, mas não concentre a saída das tarefas.",
   "Do not show notifications but focus tasks output.": "Não mostre notificações, mas concentre a saída das tarefas.",
   "Show notifications and focus tasks output.": "Mostre notificações e concentre a saída das tarefas.",
+  "OpenOCD Adaptor (serial & location)": "Adaptador OpenOCD (serial e localização)",
+  "Set Target": "Definir alvo",
+  "Multiple connected boards were detected, but no OpenOCD adapter is selected (serial/location). To avoid flashing the wrong device, set the target for the connected board and rebuild.": "Várias placas conectadas foram detectadas, mas nenhum adaptador OpenOCD foi selecionado (serial/localização). Para evitar gravar o dispositivo errado, defina o alvo da placa conectada e reconstrua o projeto.",
   "Select the output and notification mode": "Selecione o modo de saída e notificação",
   "Notification mode has changed to {mode}": "O modo de notificação mudou para {mode}",
   "No project configuration found": "Nenhuma configuração de projeto encontrada",
diff --git a/l10n/bundle.l10n.ru.json b/l10n/bundle.l10n.ru.json
@@ -28,6 +28,9 @@
   "Show notifications but do not focus tasks output.": "Показывать уведомления, но не фокусировать вывод задач.",
   "Do not show notifications but focus tasks output.": "Не показывать уведомления, но сосредоточить вывод задач.",
   "Show notifications and focus tasks output.": "Показывать уведомления и фокусировать вывод задач.",
+  "OpenOCD Adaptor (serial & location)": "Адаптер OpenOCD (серийный номер и расположение)",
+  "Set Target": "Задать цель",
+  "Multiple connected boards were detected, but no OpenOCD adapter is selected (serial/location). To avoid flashing the wrong device, set the target for the connected board and rebuild.": "Обнаружено несколько подключённых плат, но не выбран адаптер OpenOCD (серийный номер/расположение). Чтобы избежать прошивки неправильного устройства, задайте цель для подключённой платы и пересоберите проект.",
   "Select the output and notification mode": "Выберите режим вывода и уведомления",
   "Notification mode has changed to {mode}": "Режим уведомлений изменен на {mode}",
   "No project configuration found": "Конфигурация проекта не найдена",
diff --git a/l10n/bundle.l10n.zh-CN.json b/l10n/bundle.l10n.zh-CN.json
@@ -28,6 +28,9 @@
   "Show notifications but do not focus tasks output.": "显示通知，但不显示任务输出。",
   "Do not show notifications but focus tasks output.": "不显示通知，但显示任务输出。",
   "Show notifications and focus tasks output.": "同时显示通知和任务输出。",
+  "OpenOCD Adaptor (serial & location)": "OpenOCD 适配器（序列号与位置）",
+  "Set Target": "设置目标",
+  "Multiple connected boards were detected, but no OpenOCD adapter is selected (serial/location). To avoid flashing the wrong device, set the target for the connected board and rebuild.": "检测到多个已连接的开发板，但未选择 OpenOCD 适配器（序列号/位置）。为避免烧录到错误的设备，请为已连接的开发板设置目标并重新构建项目。",
   "Select the output and notification mode": "选择输出和通知模式",
   "Notification mode has changed to {mode}": "通知模式已改为 {mode}",
   "No project configuration found": "找不到项目配置",
diff --git a/package.json b/package.json
@@ -74,6 +74,7 @@
     "onCommand:espIdf.apptrace",
     "onCommand:espIdf.heaptrace",
     "onCommand:espIdf.openOCDCommand",
+    "onCommand:espIdf.openOcdAdapterStatusBar",
     "onCommand:espIdf.apptrace.archive.refresh",
     "onCommand:espIdf.apptrace.archive.showReport",
     "onCommand:espIdf.apptrace.customize",
@@ -1479,6 +1480,11 @@
         "title": "%espIdf.openOCDCommand.title%",
         "category": "ESP-IDF"
       },
+      {
+        "command": "espIdf.openOcdAdapterStatusBar",
+        "title": "%espIdf.openOcdAdapterStatusBar.title%",
+        "category": "ESP-IDF"
+      },
       {
         "command": "espIdf.partition.table.refresh",
         "title": "%espIdf.partition.table.refresh.title%",
diff --git a/package.nls.json b/package.nls.json
@@ -70,6 +70,7 @@
   "espIdf.ninja.summary.title": "Show Ninja Build Summary",
   "espIdf.openDocUrl.title": "Open ESP-IDF Documentation...",
   "espIdf.openOCDCommand.title": "OpenOCD Manager",
+  "espIdf.openOcdAdapterStatusBar.title": "OpenOCD Adaptor (serial & location)",
   "espIdf.partition.table.refresh.title": "Refresh Partition Table",
   "espIdf.pickAWorkspaceFolder.title": "Pick a Workspace Folder",
   "espIdf.projectConf.title": "Select Project Configuration",
diff --git a/src/cmdTreeView/cmdStore.ts b/src/cmdTreeView/cmdStore.ts
@@ -50,6 +50,7 @@ export enum CommandKeys {
   CustomTask = "espIdf.customTask",
   QemuServer = "espIdf.qemuCommand",
   OpenOCD = "espIdf.openOCDCommand",
+  OpenOcdAdapterStatusBar = "espIdf.openOcdAdapterStatusBar",
 }
 
 export enum AdvancedCommandKeys {
@@ -300,6 +301,14 @@ export function createCommandDictionary(): Record<
       iconId: "server-environment",
       tooltip: l10n.t("OpenOCD Server"),
     },
+    [CommandKeys.OpenOcdAdapterStatusBar]: {
+      checkboxState: ESP.GlobalConfiguration.store.get<TreeItemCheckboxState>(
+        CommandKeys.OpenOcdAdapterStatusBar,
+        TreeItemCheckboxState.Unchecked
+      ),
+      iconId: "link",
+      tooltip: l10n.t("OpenOCD Adaptor (serial & location)"),
+    },
     [CommandKeys.Debug]: {
       checkboxState: ESP.GlobalConfiguration.store.get<TreeItemCheckboxState>(
         CommandKeys.Debug,
diff --git a/src/espIdf/openOcd/adapterSerial.ts b/src/espIdf/openOcd/adapterSerial.ts
@@ -21,7 +21,8 @@ import { ESP } from "../../config";
 import { Logger } from "../../logger/logger";
 
 /**
- * Key used to store the OpenOCD USB adapter serial number in workspace state
+ * Key used to store the OpenOCD USB adapter serial number in the extension workspace state
+ * (VS Code `context.workspaceState` via `ESP.ProjectConfiguration.store`), not in user/workspace settings.json.
  */
 const OPENOCD_ADAPTER_SERIAL_KEY = "openocd.usbAdapterSerial";
 
diff --git a/src/espIdf/openOcd/openOcdManager.ts b/src/espIdf/openOcd/openOcdManager.ts
@@ -30,7 +30,7 @@ import {
 } from "../../utils";
 import { TCLClient, TCLConnection } from "./tcl/tclClient";
 import { ESP } from "../../config";
-import { statusBarItems } from "../../statusBar";
+import { statusBarItems, updateOpenOcdAdapterStatusBarItem } from "../../statusBar";
 import {
   CommandKeys,
   createCommandDictionary,
@@ -186,8 +186,22 @@ export class OpenOCDManager extends EventEmitter {
       this.workspace
     ) as string[];
 
+    const storedSerial = getStoredAdapterSerial(this.workspace);
+    const needsSerialDiscovery = !storedSerial;
+
     if (openOcdLaunchArgs && openOcdLaunchArgs.length > 0) {
       openOcdArgs.push(...openOcdLaunchArgs);
+
+      // If no adapter serial is stored yet, ensure OpenOCD runs at least at -d2
+      // so the usb-jtag serial line is printed and can be parsed.
+      if (
+        needsSerialDiscovery &&
+        !openOcdArgs.some(
+          (a) => typeof a === "string" && a.match(/^-d-?\d+$/)
+        )
+      ) {
+        openOcdArgs.unshift("-d2");
+      }
     } else {
       const openOcdConfigFilesList = idfConf.readParameter(
         "idf.openOcdConfigs",
@@ -203,14 +217,25 @@ export class OpenOCDManager extends EventEmitter {
         );
       }
 
-      const openOcdDebugLevel = idfConf.readParameter(
+      const openOcdDebugLevelRaw = idfConf.readParameter(
         "idf.openOcdDebugLevel",
         this.workspace
-      ) as string;
-      openOcdArgs.push(`-d${openOcdDebugLevel}`);
+      ) as unknown;
+      const parsedLevel =
+        typeof openOcdDebugLevelRaw === "number"
+          ? openOcdDebugLevelRaw
+          : parseInt(String(openOcdDebugLevelRaw), 10);
+      const hasValidLevel = Number.isFinite(parsedLevel);
+      const debugLevelToUse =
+        needsSerialDiscovery
+          ? Math.max(hasValidLevel ? parsedLevel : 0, 2)
+          : hasValidLevel
+            ? parsedLevel
+            : 0;
+
+      openOcdArgs.push(`-d${debugLevelToUse}`);
 
       // Inject adapter serial command if we have a stored serial number
-      const storedSerial = getStoredAdapterSerial(this.workspace);
       if (storedSerial) {
         openOcdArgs.push("-c", `adapter serial ${storedSerial}`);
       }
@@ -239,6 +264,7 @@ export class OpenOCDManager extends EventEmitter {
       const serialNumber = parseAdapterSerialFromLog(data);
       if (serialNumber && this.workspace) {
         storeAdapterSerial(this.workspace, serialNumber);
+        updateOpenOcdAdapterStatusBarItem(this.workspace);
       }
       
       const regex = /Error:.*/i;
@@ -266,6 +292,7 @@ export class OpenOCDManager extends EventEmitter {
       const serialNumber = parseAdapterSerialFromLog(data);
       if (serialNumber && this.workspace) {
         storeAdapterSerial(this.workspace, serialNumber);
+        updateOpenOcdAdapterStatusBarItem(this.workspace);
       }
       
       this.emit("data", this.chan);
diff --git a/src/espIdf/setTarget/DevkitsCommand.ts b/src/espIdf/setTarget/DevkitsCommand.ts
@@ -34,7 +34,10 @@ export class DevkitsCommand {
     this.workspaceRoot = workspaceRoot;
   }
 
-  public async runDevkitsScript(openOCDVersion: string): Promise<string> {
+  public async runDevkitsScript(
+    openOCDVersion: string,
+    opts?: { silent?: boolean }
+  ): Promise<string> {
     try {
       const workspaceFolder = vscode.workspace.getWorkspaceFolder(
         this.workspaceRoot
@@ -90,12 +93,26 @@ export class DevkitsCommand {
       // to allow scanning all available devices, not just the one at the configured location
       delete modifiedEnv.OPENOCD_USB_ADAPTER_LOCATION;
 
-      OutputChannel.init();
-      OutputChannel.appendLine(
-        "Running ESP Detect Config...",
-        "ESP Detect Config"
-      );
-      OutputChannel.show();
+      const isSilent = !!opts?.silent;
+      if (!isSilent) {
+        OutputChannel.init();
+        OutputChannel.appendLine(
+          "Running ESP Detect Config...",
+          "ESP Detect Config"
+        );
+        OutputChannel.show();
+      }
+
+      if (isSilent) {
+        // Silent mode: no progress UI, no output channel, no completion notification.
+        return await execChildProcess(
+          pythonBinPath,
+          [scriptPath, "--esp-config", espConfigPath],
+          this.workspaceRoot.fsPath,
+          undefined,
+          { env: modifiedEnv }
+        );
+      }
 
       return await vscode.window.withProgress(
         {
@@ -136,9 +153,14 @@ export class DevkitsCommand {
       const msg = error.message
         ? error.message
         : "Error running ESP Detect Config";
-      Logger.errorNotify(msg, error, "DevkitsCommand");
-      OutputChannel.appendLine(msg, "ESP Detect Config");
-      OutputChannel.show();
+      if (opts?.silent) {
+        Logger.error(msg, error, "DevkitsCommand");
+        throw error;
+      } else {
+        Logger.errorNotify(msg, error, "DevkitsCommand");
+        OutputChannel.appendLine(msg, "ESP Detect Config");
+        OutputChannel.show();
+      }
     }
   }
 
diff --git a/src/espIdf/setTarget/index.ts b/src/espIdf/setTarget/index.ts
@@ -41,9 +41,9 @@ import { updateCurrentProfileIdfTarget } from "../../project-conf";
 import { DevkitsCommand } from "./DevkitsCommand";
 import {
   clearAdapterSerial,
-  getStoredAdapterSerial,
 } from "../openOcd/adapterSerial";
 import { SerialPort } from "../serial/serialPort";
+import { updateOpenOcdAdapterStatusBarItem } from "../../statusBar";
 
 export let isSettingIDFTarget = false;
 
@@ -211,6 +211,7 @@ export async function setIdfTarget(
           configurationTarget,
           workspaceFolder.uri
         );
+        updateOpenOcdAdapterStatusBarItem(workspaceFolder.uri);
         await updateCurrentProfileIdfTarget(
           selectedTarget.idfTarget.target,
           workspaceFolder.uri
diff --git a/src/extension.ts b/src/extension.ts
diff --git a/src/project-conf/ProjectConfigurationManager.ts b/src/project-conf/ProjectConfigurationManager.ts
diff --git a/src/statusBar/index.ts b/src/statusBar/index.ts
