fix: Implement OpenOCD adapter serial pinning

bundles/com.espressif.idf.core/src/com/espressif/idf/core/build/IDFLaunchConstants.java

@@ -19,6 +19,7 @@ public final class IDFLaunchConstants
 	public static final String SERIAL_MONITOR_ENCODING = "SERIAL_MONITOR_ENCODING"; //$NON-NLS-1$
 	public static final String BUILD_FOLDER_PATH = "com.espressif.idf.launch.serial.core.idfBuildFolderPath"; //$NON-NLS-1$
 	public static final String OPENOCD_USB_LOCATION = "OPENOCD_USB_ADAPTER_LOCATION"; //$NON-NLS-1$
+	public static final String OPENOCD_ADAPTER_SERIAL = "OPENOCD_ADAPTER_SERIAL"; //$NON-NLS-1$
 	public static final String FLASH_ENCRYPTION_ENABLED = "com.espressif.idf.launch.FLASH_ENCRYPTION_ENABLED"; //$NON-NLS-1$
 
 }

bundles/com.espressif.idf.core/src/com/espressif/idf/core/util/OpenOcdVersionManager.java

@@ -27,6 +27,22 @@ private OpenOcdVersionManager()
 	private static final Pattern VERSION_PATTERN = Pattern.compile(
 			"(?i)(?:Open On-Chip Debugger\\s+|v)(?<major>\\d+)\\.(?<minor>\\d+)(?:\\.(?<patch>\\d+))?(?:-[a-z0-9]+-(?<build>\\d+))?"); //$NON-NLS-1$
 
+	// OpenOCD >= v0.12.0-esp32-20260424: `adapter usb location` command.
+	private static final int ADAPTER_USB_LOCATION_MIN_BUILD = 20260424;
+
+	// OpenOCD >= v0.12.0-esp32-20260304: `adapter serial` command.
+	private static final int ADAPTER_SERIAL_FROM_DETECT_MIN_BUILD = 20260304;
+
+	public static boolean supportsAdapterUsbLocationCommand(String executablePath)
+	{
+		return getVersion(executablePath).isBuildDateAtLeast(0, 12, ADAPTER_USB_LOCATION_MIN_BUILD);
+	}
+
+	public static boolean supportsSerialFromDetectConfig(String executablePath)
+	{
+		return getVersion(executablePath).isBuildDateAtLeast(0, 12, ADAPTER_SERIAL_FROM_DETECT_MIN_BUILD);
+	}
+
 	public static class OpenOcdVersion
 	{
 		public final int major;

bundles/com.espressif.idf.debug.gdbjtag.openocd/src/com/espressif/idf/debug/gdbjtag/openocd/Configuration.java

@@ -122,6 +122,16 @@ public static String[] getGdbServerCommandLineArray(ILaunchConfiguration configu
 					lst.add("-c");
 					lst.add(String.format("adapter usb location %s", openocdLoc));
 				}
+
+				// Pin adapter by serial from esp_detect_config.py (OpenOCD >= v0.12.0-esp32-20260304).
+				String adapterSerial = activeLaunchTarget.getAttribute(IDFLaunchConstants.OPENOCD_ADAPTER_SERIAL,
+						(String) null);
+				if (adapterSerial != null && !adapterSerial.isEmpty()
+						&& OpenOcdVersionManager.supportsSerialFromDetectConfig(executable))
+				{
+					lst.add("-c");
+					lst.add(String.format("adapter serial %s", adapterSerial));
+				}
 			}
 
 			lst.add("-c"); //$NON-NLS-1$

bundles/com.espressif.idf.launch.serial.ui/src/com/espressif/idf/launch/serial/ui/internal/NewSerialFlashTargetWizard.java

@@ -69,6 +69,7 @@ public boolean performFinish()
 		wc.setAttribute(LaunchBarTargetConstants.FLASH_VOLTAGE, page.getVoltage());
 
 		setOpenOCDAdaptorLocation(wc);
+		setOpenOCDAdapterSerial(wc);
 
 		wc.save();
 		storeLastUsedSerialPort();
@@ -119,6 +120,19 @@ else if (usbLocation.startsWith("usb://")) //$NON-NLS-1$
 		}
 	}
 
+	private void setOpenOCDAdapterSerial(ILaunchTargetWorkingCopy wc)
+	{
+		String serial = page.getSelectedBoardSerialNumber();
+		if (StringUtil.isEmpty(serial))
+		{
+			wc.setAttribute(IDFLaunchConstants.OPENOCD_ADAPTER_SERIAL, null); // nullify existing one
+		}
+		else
+		{
+			wc.setAttribute(IDFLaunchConstants.OPENOCD_ADAPTER_SERIAL, serial);
+		}
+	}
+
 	private void storeLastUsedSerialPort()
 	{
 		Preferences preferences = InstanceScope.INSTANCE.getNode(Activator.PLUGIN_ID);

bundles/com.espressif.idf.launch.serial.ui/src/com/espressif/idf/launch/serial/ui/internal/NewSerialFlashTargetWizardPage.java

@@ -86,6 +86,8 @@ public class NewSerialFlashTargetWizardPage extends WizardPage
 	private Combo fBoardCombo;
 	private Combo fFlashVoltage;
 	private String previousBoard = null;
+	// Board combo display name -> serial_number from esp_detect_config.py
+	private final Map<String, String> boardSerialByDisplayName = new HashMap<>();
 
 	protected boolean isOutputDetailed;
 	public static final String PREF_ENABLE_DETAILED_OUTPUT = Activator.PLUGIN_ID + ".enableDetailedOutput"; //$NON-NLS-1$
@@ -145,6 +147,7 @@ public void widgetSelected(SelectionEvent e)
 				Shell shell = display.getActiveShell();
 				final List<String> boardDisplayNames = new ArrayList<>();
 				final String[] jsonHolder = new String[1];
+				boardSerialByDisplayName.clear();
 				try
 				{
 					ProgressMonitorDialog dialog = new ProgressMonitorDialog(shell);
@@ -610,6 +613,11 @@ public String getSelectedBoardUsbLocation()
 		return null;
 	}
 
+	public String getSelectedBoardSerialNumber()
+	{
+		return boardSerialByDisplayName.get(fBoardCombo.getText());
+	}
+
 	/**
 	 * Returns a list of display names for boards matching the selected target. Each display name is formatted as
 	 * "<name> [<location>]".
@@ -624,7 +632,13 @@ private List<String> getBoardDisplayNamesForTarget(String selectedTarget, JSONAr
 			{
 				String name = (String) board.get("name"); //$NON-NLS-1$
 				String location = (String) board.get("location"); //$NON-NLS-1$
-				boardDisplayNames.add(String.format("%s [%s]", name, location)); //$NON-NLS-1$
+				String serialNumber = (String) board.get("serial_number"); //$NON-NLS-1$
+				String displayName = String.format("%s [%s]", name, location); //$NON-NLS-1$
+				boardDisplayNames.add(displayName);
+				if (!StringUtil.isEmpty(serialNumber))
+				{
+					boardSerialByDisplayName.put(displayName, serialNumber);
+				}
 			}
 		}
 		return boardDisplayNames;