How to use the debugger with Xenon, Boron

@v8dave: Here is my guide to setting up Visual Studio Code and OpenOCD on Ubuntu Linux to do source code debugging with the Xenon/Argon and Particle debugger. It took a while, but it is now working!

  1. To install OpenOCD on Ubuntu Linux:

    sudo apt install openocd

    Mine ends up in /usr/bin/openocd and /usr/share/openocd

  2. Download the OpenOCD target file nrf52-var.cfg.
    I put mine in /usr/share/openocd/scripts/target/

  3. For your operating system, download Visual Studio Code.

  4. Apply for and download the Particle Workbench, Themes, and Code Snippets extensions (currently 1.0.0-alpha.6) for VS Code Here.

  5. In VS Code, press the Extensions button on the left, go up to the (More Actions) menu and pick Install from VSIX… and one by one, install your previously downloaded Particle extensions, Workbench last, and follow the prompts. Make sure the Cortex-Debug extension is installed.

  6. In VS Code, set up your Project and customize the YourProgram.code-workspace file to look similar to this:

    "settings": {
        "extensions.ignoreRecommendations": true,
        "C_Cpp.default.configurationProvider": "particle.particle-vscode-core",
        "particle.targetPlatform": "xenon",
        "files.associations": {
            "*.ino": "cpp"
        "particle.firmwareVersion": "0.8.0-rc.27",
        "particle.targetDevice": "Xen1Mesh",
        "cortex-debug.openocdPath": "/usr/bin/openocd"
    "folders": [
            "path": "."

  1. In VS Code, customize your launch.json file to look similar to this:
    "version": "0.1.0",
    "configurations": [ 
        "name": "Debug (OpenOCD)",
        "cwd": "${workspaceRoot}",
        "executable": "./target/Xen_BME280_Node.elf",
        "request": "attach",
        "type": "cortex-debug",
        "servertype": "openocd",
        "configFiles": [

If you change "request": to "launch" type, it does not work properly, the Debugging session gets lost and corrupts the Particle Device OS. You will then have to re-flash the Particle Device OS !

  1. Connect your Xenon to a usb port on your computer and place it in DFU mode (RGB LED blinking Yellow) for local flashing.

  2. In VS Code, code your program, press Ctrl-shift-b to bring up the Particle Build commands and pick Particle: Flash application for debug (local). Place a couple of breakpoints in your program for testing.

  3. Connect the Particle (mesh) Debugger cable to the Xenon SWD port and plug in the interface to another usb port. Remember not to use pin D7 (User LED) in your own programs because it will mess up SWD debugging!

  4. In VS Code, press the Debug button on the left then the green arrow above it to start debugging. Your Particle Debugger board should be blinking blue frenetically. This is good! Now look at your source file. The debugger never made it to your breakpoints. Select the Debug Console and see that your program is paused. Now press on the floating Debugger panel Continue (F5) button and wait a long time for it to get to the first breakpoint. You are ready to debug when the breakpoint is highlighted in yellow. You made it!

  5. At the bottom of the Debug Console is a prompt > to enter GDB commands like help and you can talk to the debugger interface with monitor commands like monitor help. This is the same as telnet localhost 4444 from a terminal to talk to the interface through OpenOCD.

  6. Other useful consoles are Output with Adapter Output selected. Also press F1 and select Particle: Serial Monitor to see your program’s usb output on the Terminal.

  7. When done debugging, select Stop Debugging from the Debug menu. Before you can debug another session, you will need to press reset on the Xenon board.

  8. Some Gotchas: You only have 2 breakpoints. If you add more, it will only cycle through the first two! So, when the 2nd breakpoint is hit, remove the first, move it down below the last breakpoint and continue to slinky down as you debug! Even though the breakpoints might be close together in loop(), the debugger will cycle through setup() to get to that 2nd breakpoint! Doesn’t make a lot of sense, but that is the current behavior . . .

  9. If you are having difficulties flashing locally with usb and accessing the usb port, you may have smacked up against the UDEV Wall! You should download 50-particle.rules and then

sudo cp 50-particle.rules /etc/udev/rules.d/ 

and restart your system.

I hope this info has saved you some time! Happy debugging . . .