Skip to content

Conversation

@radurentea
Copy link
Collaborator

@radurentea radurentea commented Nov 20, 2025

Description

This PR introduces support for identifying OpenOCD USB adapters by their serial number (MAC address), improving the reliability of multi-device setups. It also fixes device detection issues by ensuring scans aren't constrained by previous location settings and optimizes OpenOCD version checks.

OpenOCD Adapter Serial Support

  • Added Serial Number Tracking: Implemented logic to parse, store, and retrieve the USB adapter's serial number (MAC address) from OpenOCD logs.
  • Target Specificity: The extension now injects adapter serial <serial> into OpenOCD commands when a specific adapter has been identified, taking precedence over OPENOCD_USB_ADAPTER_LOCATION.
  • New Module: Created src/espIdf/openOcd/adapterSerial.ts to handle serial number logic.

Device Detection Improvements

  • Unrestricted Scanning: Modified DevkitsCommand to temporarily unset OPENOCD_USB_ADAPTER_LOCATION during device detection. This ensures the scan checks all available devices rather than just the currently configured one.
  • Clean State: setIdfTarget now clears stored adapter serials and locations when selecting a new target to prevent stale configuration issues.
  • Automatic Port Selection: Setting a connected device target now automatically detects and updates the serial port configuration to match the selected device. This change was made mainly for not having to change port manually before running monitor, which is a common use case for the users.

Performance

  • Silent Version Checks: Updated OpenOCDManager.version() to support a silent mode, reducing log noise during frequent version checks in the hints provider.

Type of change

Please delete options that are not relevant.

  • Bug fix (non-breaking change which fixes an issue)

Steps to test this pull request

  1. In a project, you should be able to switch between targets (not connected and connected) without any issues, even if you have two similar boards connected. Also, if the selected target is a connected board, the serial port should also be changed to the correct one.

How has this been tested?

Same as described above

Test Configuration:

  • ESP-IDF Version: 5.5.1
  • OS (Windows,Linux and macOS): Windows

Checklist

  • PR Self Reviewed
  • Applied Code formatting
  • Added Documentation
  • Added Unit Test
  • Verified on all platforms - Windows,Linux and macOS

@radurentea radurentea self-assigned this Nov 20, 2025
@github-actions
Copy link

github-actions bot commented Nov 20, 2025

Download the artifacts for this pull request:
You can test these changes by installing this VSIX by click menu View -> Command Palette..., type Install from VSIX and then select downloaded esp-idf-extension.vsix file to install the extension.

@brianignacio5
Copy link
Collaborator

The thing about this logic is only applies when user run the setTarget command.

I'm wondering for the case: 1) User has connected board, 2) Run set target, 3) value is set in customExtraVars 4) Time passes user disconnect board 5) User tries to use OpenOCD Server directly and it doesn't work ? USB_ADAPTER_LOCATION is changed ?

Copy link
Collaborator

@Fabricio-ESP Fabricio-ESP left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed Working.
Thanks for the change.

Copy link
Collaborator

@brianignacio5 brianignacio5 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some minor changes but one really required change in src/espIdf/setTarget/index.ts line 206 comment.

…ed the declaration of customExtraVars to a single location and added logic to clear OPENOCD_USB_ADAPTER_LOCATION when no board location is available or when switching to a non-connected target.
Clear the OPENOCD_USB_ADAPTER_LOCATION setting when switching to a target
that doesn't have a USB location, preventing OpenOCD from using stale device
addresses from previous targets.

Create a plain object copy of customExtraVars to avoid proxy issues when
deleting properties, and remove unnecessary configuration re-read.
Remove OPENOCD_USB_ADAPTER_LOCATION from environment during device detection
so the script can scan all available devices, not just the one at the
configured location.
- Added extra bool parameter for running openOCDManager.version() with default value false, for not silencing the output from it.
Parse and store USB adapter serial numbers from OpenOCD logs and use
them as the primary identifier for adapter connections, with fallback
to OPENOCD_USB_ADAPTER_LOCATION. Serial numbers are more reliable than
USB locations which can change when devices are reconnected.

- Parse serial from OpenOCD log output (format: "Info : esp_usb_jtag: serial (XX:XX:XX:XX:XX:XX)")
- Store serial in workspace state for persistence
- Inject 'adapter serial' command when starting OpenOCD
- Clear serial/location when target changes
- Auto-update serial port when switching to connected target
- Remove location restriction during device detection
Remove async/Promise wrapping from storeAdapterSerial and clearAdapterSerial
since they only perform synchronous workspaceState operations.
Add platform-specific USB bus/port parsing to match OpenOCD devices to serial ports.
@radurentea radurentea added this to the v1.11.0 milestone Dec 9, 2025
Copy link
Collaborator

@brianignacio5 brianignacio5 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants