Debugging Arduino Nano 33 BLE with Arduino IDE v2

[xrk]

This is to recap older posts about debugging Arduino Nano 33 BLE with nRF52840 microcontroller via SWD that were at the time discussed for beta version of Arduino IDE v2 in threads Debugging nano 33 BLE with IDE 2-b4. Debug configuration? and Information about debugging?
I decided to do a rewrite, especially as there are some minor, but nevertheless relevant changes how Arduino Nano 33 BLE can be in-circuit-debugged with the release version of Arduino IDE v2. Officially, in-circuit-debugging of Arduino Nano 33 BLE is not yet supported according to: https://docs.arduino.cc/software/ide-v2/tutorials/ide-v2-debugger , but as you can see below, it does work with some manual work.

For in-circuit-debugging, a hardware debugger is required. For the tests, I used Segger J-Link EDU mini, attached to Serial-Wire-Debug (SWD) port of the Arduino Nano 33 BLE (try to use as short cables as possible):

The following example uses Windows, adjust accordingly, if you use another OS (especially, if using Linux or Mac, please see the post by ptillisch from Arduino Team below for further tips). To proceed:

1. Install Arduino IDE v2 (tested with v2.0.3): https://www.arduino.cc/en/software
2. Install latest Segger J-Link Software and Documentation Pack: SEGGER - The Embedded Experts - Downloads - J-Link / J-Trace
3. Start Arduino IDE and open Board Manager (Tools -> Board -> Board Manager) and install "Arduino Mbed OS Nano boards" (at the time of writing v3.5.4)
4. Create a sketch, for example, I will use the File -> Examples -> 01.Basics -> Blink that I copy to a new location.
5. Close Arduino IDE for now.
6. In the same folder, where the sketch *.ino file is residing, create, e.g. with a text editor, debug_custom.json with following content:

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

In case you installed the Segger J-Link software to another location, adjust the serverpath accordingly.
7. In the folder, where the sketch *.ino file is residing, create a subfolder .theia (do note the dot in the beginning!) and in .theia subfolder create a file launch.json with following content:

{
  "version": "0.2.0",
  "configurations": [
    {
      "cwd": "${workspaceFolder}",
      "executable": "./bin/executable.elf",
      "name": "Debug with JLink",
      "request": "launch",
      "type": "cortex-debug",
      "device": "",
      "runToEntryPoint": "main",
      "showDevDebugOutput": "none",
      "servertype": "jlink"
    },
  ]
}

8. Under your user profile (in Windows C:\Users\<username>) navigate to AppData\Local\Arduino15\packages\arduino\hardware\mbed_nano\3.5.4 and create there a platform.local.txt file with the following content:

debug.executable={build.path}/{build.project_name}.elf
debug.toolchain=gcc
debug.toolchain.path={runtime.tools.arm-none-eabi-gcc-7-2017q4.path}/bin/
debug.toolchain.prefix=arm-none-eabi-
debug.server=openocd
debug.server.openocd.path={runtime.tools.openocd-0.10.0-arduino7.path}/bin/openocd
debug.server.openocd.scripts_dir={runtime.tools.openocd-0.10.0-arduino7.path}/share/openocd/scripts/
debug.server.openocd.script={runtime.platform.path}/variants/{build.variant}/{build.openocdscript}

Please do note that the AppData folder is hidden by default in Windows.
9. Attach the J-Link debugger as well as Arduino Nano 33 BLE to your computer via 2 USB cables.
10. Open the sketch in Arduino IDE v2, select under Tools -> Board -> Arduino Mbed OS Nano Boards -> Arduino Nano 33 BLE
11. Put a breakpoint at the beginning of the setup() function block (by clicking in front of the line number) and click Start Debugging icon (the third icon from the left on top of the IDE).

You should now be able to step through code, set breakpoints and inspect variables.

In case anyone has any tips or improvement suggestions to the above, I would be very interested to hear them.

[ptillisch]

Thanks so much for taking the time to share this knowledge @xrk!

I'm wondering about why it is necessary to manually create the launch.json file. Arduino IDE 2.x automatically generates a launch.json file from the properties in the platform.txt file of the selected board. If a debug_custom.json file is present in the sketch, its fields are merged in to the configurations[0] field of the generated launch.json file. So it seems to me it should not be necessary for the user to manually create a launch.json file, but I haven't tried this so maybe I'm missing something.

---

As for improvements, I have a couple suggestions:

Use platform.local.txt to add the platform debugger configuration

@xrk

open the platform.txt file and add following lines to the end:

This is perfectly valid, but it might be more convenient to leave platform.txt alone and instead add a file named platform.local.txt to the C:\Users\<username>\AppData\Local\Arduino15\packages\arduino\hardware\mbed_nano\3.5.4 folder:

https://arduino.github.io/arduino-cli/latest/platform-specification/#platformlocaltxt

The user will need to make this modification to the platform after every update of the "Arduino Mbed OS Nano Boards" platform (which has a fairly short release cycle). That is still the case when using the platform.local.txt, but the user can store a copy of that file in a separate location and then just copy it into the folder after every update, which is a little more convenient than having to add the text. You could even provide a platform.local.txt file as a downloadable attachment.

It is also a little bit safer to avoid having users modifying platform.txt. If they inadvertently changed some of the other content of the file while adding the debugger configuration lines, it could result in some confusing errors while compiling or uploading.

Make tutorial cross-platform

The path to the platform provided at step (8) is Windows-specific. The tutorial could be made cross-platform by simply listing the paths for Linux and macOS as well:

• Linux:

  ~/.arduino15/packages/arduino/hardware/mbed_nano/3.5.4
  

• macOS:

  ~/Library/Arduino15/packages/arduino/hardware/mbed_nano/3.5.4
  

Mention that platform is under a hidden folder

Unfortunately the default configuration of file browsers of all three operating systems hide a parent folder of the platform from the user:

• Windows File Explorer hides C:\Users\<username>\AppData\
• The "GNOME Files" file manager included in some Linux distros (e.g., Ubuntu) hides ~/.arduino15/ (because it is a dotfile)
• macOS Finder hides ~/Library/

I have observed this periodically causes confusion to Arduino users because it appears to them that the specified folder does not exist on their system. This might be less likely for the advanced users your tutorial is targeted to.