Starting 2.3.0 debugger with J-Link fails: "unable to find CMSIS-DAP device"

ptillisch · March 3, 2024, 7:12am

Hi @HarrySatt. A significant rework of the debugger configuration system was released in Arduino IDE 2.3.0. This was necessary because as more and more Arduino boards platforms started taking advantage of the debugger feature, some advanced requirements emerged that were not properly accommodated by the original the initial experimental system.

The new system is more powerful and flexible, so this change will greatly benefit the platform developers and users in the years to come, but unfortunately it does require that those who are using a J-Link debug probe (or any other configuration that requires the use of the IDE's debug_custom.json feature) must make some adjustments to their workflow.

Instructions

Open the sketch you want to debug in Arduino IDE.
Select the "debug_custom.json" editor tab.
Add this line at the top of the file:
```
[
```
Add this line at the top of the file:
```
]
```

Add the following lines in the middle of the file

"configId": "arduino:samd:mkrwan1310:programmer=jlink",
"server": "jlink",
"serverPath": "<JLinkGDBServer path>",

Replace <JLinkGDBServer path> with the path to the J-Link GDB server tool, which you will find in the value of the existing serverpath key (note the lowercase p in path).
You should now have something like this:

[
  {
    "servertype": "jlink",
    "device": "ATSAMD21G18",
    "configId": "arduino:samd:mkrwan1310:programmer=jlink",
    "server": "jlink",
    "serverPath": "C:/Program Files/JLink/JLinkGDBServerCL",
    "interface": "swd",
    "serverpath": "C:/Program Files/JLink/JLinkGDBServerCL"
  }
]

Select File > Save from the Arduino IDE menus.
Select Tools > Board > Arduino SAMD Boards (32-bits ARM Cortex-M0+) > Arduino MKR WAN 1310 from the Arduino IDE menus.
Select Tools > Programmer > Segger J-Link from the Arduino IDE menus.
Select Sketch > Optimize for Debugging from the Arduino IDE menus (if it is not already enabled).
Select Sketch > Verify/Compile from the Arduino IDE menus.
Wait for the compilation to finish successfully.
Connect your J-Link and MKR WAN 1310 to your computer as usual.
Click the "Start Debugging" button on the Arduino IDE toolbar.

The debugger should now start up and work as expected.

Please let me know if you have any questions or problems while following those instructions.

Explanation

The instructions above will allow you to get back to using the debugger in this specific application of a J-Link debug probe and a MKR WAN 1310 board, but you (or others who have similar questions and find this thread during their researches) might be interested in understanding why these changes were necessary and how you might make equivalent migrations for other configurations. I'll provide relevant information below. If you aren't interested in "the boring details", you can feel free to skip the rest of this reply.

There are two separate factors you should be aware of:

Breaking change to `debug_custom.json` format

Previously, the data structure of the file was an object. For example:

{
  "servertype": "jlink",
  "device": "ATSAMD21G18",
  "interface": "SWD",
  "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL"
}

It is now an array of objects. For example:

[
  {
    "servertype": "jlink",
    "device": "ATSAMD21G18",
    "interface": "SWD",
    "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL"
  }
]

The benefit of this new structure is that it allows you to define multiple custom debugger configurations. For this reason, it is necessary to provide an identifier for each configuration so that Arduino IDE will know which one is appropriate to apply. This is done via the configId key. The value has the following format:

<board FQBN>:programmer=<programmer ID>

For example:

[
  {
    "configId": "arduino:samd:mkrwan1310:programmer=jlink",
    "servertype": "jlink",
    "device": "ATSAMD21G18",
    "interface": "SWD",
    "serverpath": "C:/Program Files/SEGGER/JLink/JLinkGDBServerCL"
  }
]

It might seem too confusing to figure out the FQBN and programmer ID, but you can get Arduino IDE to generate it for you:

Select the board you are using from the Arduino IDE menus.
Select the debug probe you are using from the Tools > Programmer menu in Arduino IDE.
ⓘ If there is no Tools > Programmer menu, you can skip this step.
Select Sketch > Verify/Compile from the Arduino IDE menus.
Wait for the compilation to finish successfully.
Click the "Start Debugging" button on the Arduino IDE toolbar.
Wait for the process to fail, as indicated by the appearance of an error notification at the bottom right corner of the Arduino IDE menu.
ⓘ The failure is expected since we haven't yet added the configId key to the debug_custom.json file. The purpose of clicking the "Start Debugging" button is only to cause Arduino IDE to generate the configId value, which is accomplished even when the debugger doesn't successfully start.
Click the debugger icon on the activity bar on the left side of the Arduino IDE window.
The "DEBUG" view will open in the left side panel.
Click the gear icon ('Open "launch.json"') on the debugger toolbar.
A "launch.json" tab will open in the editor.
Find the appropriate configurations[*].configId key in launch.json and copy the value.
For example, if the file contains this content:
```
{
  "version": "0.2.0",
  "configurations": [
    {
      "configId": "arduino:samd:mkrwan1310:programmer=jlink",
```
Then copy the "configId": "arduino:samd:mkrwan1310:programmer=jlink",.
Select the "debug_custom.json" editor tab.
Paste the copied configId key into the file.
Select File > Save from the Arduino IDE menus.

Bug when overriding certain configuration keys

In addition to the intentionally introduced breaking change I described above, unfortunately a bug was also accidentally introduced that impacts users of the debug_custom.json feature:

github.com/arduino/vscode-arduino-tools

Not possible to override debug configuration keys that are remapped from Arduino CLI

opened 05:59AM - 03 Mar 24 UTC

closed 07:10AM - 05 Mar 24 UTC

per1234

conclusion: resolved topic: code type: imperfection

### Describe the problem This extension automatically generates a `launch.jso…n` file to configure the [**Cortex-Debug** VS Code extension](https://github.com/Marus/cortex-debug) for use with the selected board and "programmer" (debug probe). The base configuration data comes from the [`arduino-cli debug --info`](https://arduino.github.io/arduino-cli/dev/commands/arduino-cli_debug/) output. Some of that data does not match exactly with the `launch.json` format so the extension remaps it. In some cases ([example](https://docs.arduino.cc/tutorials/mkr-wifi-1010/mkr-jlink-setup/#debugging-in-arduino-ide-2)), the user might need/want to make some adjustments to the generated configuration. This is done by adding the custom configuration data to a file named `debug_custom.json` in the sketch root folder. The configuration from that file is merged into the base data when generating `launch.json`, overriding the base data where there is overlap. 🐛 Overrides no longer work for the configuration keys that are remapped from the Arduino CLI data: - `armToolchainPath` - `configFiles` - `serverpath` - `servertype` ### To reproduce --- **ⓘ** Hardware is not required to perform this demo. --- 1. If you don't already have it installed, use the Arduino IDE Boards Manager to install the "**Arduino SAMD Boards (32-bits ARM Cortex-M0+)**" platform. **ⓘ** This platform was selected arbitrarily as one that has debugger support. The fault is not platform-specific. 1. Select **File > New** from the Arduino IDE menus. 1. Select **Tools > Board > Arduino SAMD Boards (32-bits ARM Cortex-M0+) > Arduino Zero (Programming Port)** from the Arduino IDE menus. 1. Select **Tools > Programmer > Atmel EDBG** from the Arduino IDE menus. 1. Click the **●●●** icon on the right side of the editor toolbar. A menu will open. 1. Select "**New Tab**" from the menu. The "**Name for new file**" dialog will open. 1. Type `debug_custom.json` in the field in the dialog. 1. Click the "**OK**" button. The dialog will close and a "**debug_custom.json**" tab will be added to the editor view. 1. Use the editor to add the following content to the "**debug_custom.json**" tab: ```json [ { "configId": "arduino:samd:arduino_zero_edbg:programmer=edbg", "toolchainPrefix": "custom-toolchain-prefix", "armToolchainPath": "/path/to/custom-arm-toolchain", "configFiles": ["/path/to/custom-custom-config-file"], "serverpath": "/path/to/custom-server", "servertype": "jlink" } ] ``` 1. Select **Sketch > Verify/Compile** from the Arduino IDE menus. 1. Wait for the compilation to finish successfully. 1. Click the "**Start Debugging**" button on the Arduino IDE toolbar. 1. Wait for the process to fail. **ⓘ** The failure is expected unless you happen to have the necessary hardware connected to your computer. It is not relevant to the demo. 1. Click the "Toggle Debug View" icon on the activity bar. The debug view will open in the left side panel. 1. Click the gear icon ('Open "launch.json"') on the debugger toolbar. A "**launch.json**" tab will open in the editor. 🙂 The `configurations[0].toolchainPrefix` value was set according to `debug_custom.json` as expected: ```json "toolchainPrefix": "custom-toolchain-prefix" ``` 🐛 The `configurations[0].armToolchainPath`, `configurations[0].configFiles`, `configurations[0].serverpath`, and `configurations[0].servertype` values were not set according to `debug_custom.json`: ```json "armToolchainPath": "C:\\Users\\per\\AppData\\Local\\Arduino15\\packages\\arduino\\tools\\arm-none-eabi-gcc\\7-2017q4/bin/", "configFiles": [ "C:\\Users\\per\\AppData\\Local\\Arduino15\\packages\\arduino\\hardware\\samd\\1.8.14/variants/arduino_zero/openocd_scripts/arduino_zero.cfg" ], "serverpath": "C:\\Users\\per\\AppData\\Local\\Arduino15\\packages\\arduino\\tools\\openocd\\0.10.0-arduino7/bin/openocd", "servertype": "openocd" ``` ### Expected behavior Any debug configuration key can be overridden via `debug_custom.json`. ### vscode-arduino-tools version 0.1.3 ### Additional context The regression was introduced at https://github.com/arduino/vscode-arduino-tools/commit/9508d0a8500ae578f581768ecde40804d286ea62 / https://github.com/arduino/vscode-arduino-tools/pull/41 #### Additional Reports - https://forum.arduino.cc/t/starting-2-3-0-debugger-with-j-link-fails-unable-to-find-cmsis-dap-device/1230756/7 <a name="workaround"></a> #### Workaround Use the pre-remapping key names in `debug_custom.json`: - `armToolchainPath` -> `toolchainPath` - `configFiles` -> `serverConfiguration.scripts` - `serverpath` -> `serverPath` - `servertype` -> `server`

I have already submitted a fix for the bug, but it will be some time before that is available as part of an Arduino IDE build. Fortunately it is possible to workaround the bug by using different key names in your debug_custom.json file:

Original key	Workaround key
`armToolchainPath`	`toolchainPath`
`configFiles`	`serverConfiguration.scripts`
`serverpath`	`serverPath`
`servertype`	`server`

The workaround will stop working once the bug is fixed, so you should also leave the correct keys in your debug_custom.json file so that it will continue working even after you update Arduino IDE to a new version that has the fix.

Topic		Replies	Views
Setting up JLink IDE 2.x	6	2346	February 20, 2024
IDE 2.3.0 debugging esp32s3 using built-in usb jtag IDE 2.x	20	11493	June 14, 2025
Information about debugging? IDE 2.x	18	6286	October 24, 2021
Debug GIGA using IDE2 Debugger? GIGA R1 WiFi	21	2568	September 18, 2024
Arduino IDE 2.2.1 debug failure GIGA R1 WiFi	28	1703	December 10, 2023

Starting 2.3.0 debugger with J-Link fails: "unable to find CMSIS-DAP device"

Instructions

Explanation

Breaking change to debug_custom.json format

Bug when overriding certain configuration keys

Related topics

Breaking change to `debug_custom.json` format