Skip to content

How to debug

The extension offers several options for debugging your application. The default option is to use the recommended nRF Debug tool included with the extension.

Special conditions for debugging apply to applications for multi-core Systems on Chip and devices with readback protection.

Note

Ubuntu users with nRF Connect SDK v1.7.0 need to install the libcurses5 package for debugging to work properly. Run the following command:

sudo apt install libncurses5

How to enable debugging

To enable the full set of debugging options for your nRF Connect SDK application, check Enable debug options when you are setting up a build configuration.

When you add a build configuration with this option checked, the following options are automatically set:

Option Description
CONFIG_DEBUG_OPTIMIZATIONS This option limits the optimizations made by the compiler to only those that do not impact debugging.
CONFIG_DEBUG_THREAD_INFO This option adds additional information to the thread object so that the debugger can discover the threads. This will work for any debugger. Additional threads appear in the Call Stack View.

Enabling the debugging options will affect the application's memory usage.

How to enable debugging after building

If you forgot to enable the full set of debugging options during the build configuration step, complete the following steps:

  1. Right-click the build configuration.
    The drop-down menu appears.
  2. Click Edit Build Configuration.
  3. On the Edit Build Configuration screen, check Enable debug options.
  4. Click Build Configuration.
    The build configuration is rebuilt with the debug options enabled.

Note

There is a known issue where debugging may not work if you enable debug options when generating the build configuration. This seems to happen with simple sample applications, such as Blinky. Samples that use threads still seem to work with Enable debug options checked.

To work around this issue, generate the build configuration with Enable debug options unchecked. If this does not resolve the issue, instead of starting the debug session by clicking the Debug Application icon, start debugging by using Run -> Start Debugging or by pressing F5.

How to start debugging with nRF Debug

nRF Debug comes integrated with the extension and is meant for debugging applications compatible with the nRF Connect SDK. There are two default options to start debugging with nRF Debug:

For more information about general debugging, visit the VS Code debugging documentation for additional information.

How to start debugging with Ozone

Alongside the Debug option, the Actions View includes the Debug with Ozone button. This option allows you to start debugging with SEGGER Ozone, the J-Link multi-platform debugger and performance analyzer.

If you have Ozone installed, click the button to start debugging.

How to add Ozone debugging option

The option for debugging with Ozone might not be visible in the Actions View. To add it to the View, complete the following steps:

  1. Make sure you have SEGGER Ozone installed.
  2. Run nRF Connect: Debug with Ozone through the Command Palette.
    VS Code will notify you that no Ozone is found.
  3. Click Configure path... to provide the path to the Ozone executable file.
  4. Restart VS Code.

After restart, the Debug with Ozone button will appear in the Actions View.

How to debug applications for a multi-core System on Chip

If you are using a multi-core System on Chip (SoC) and want to debug the firmware on all cores simultaneously, you need to set up separate debugging sessions. If you want to debug a one-core SoC or only debug the application core firmware, a single debugging session is enough.

To debug an SoC that contains an application core and a network core:

  1. Set up two separate debug sessions to debug the firmware running on the application core and on the network core, respectively.
  2. Once both sessions are established, execute the code on the application core.
    The startup code releases the NETWORK.FORCEOFF signal to start the network core and allocates the necessary GPIO pins for it.
  3. Start code execution on the network core in the other debug session.

If you want to reset the network core while debugging, make sure to first reset the application core and execute the code.

How to recover a device with readback protection

When attempting to debug a device that has readback protection enabled, the debugger may time out with no explanation. The solution is to recover the device using the following steps:

  1. Use one of the following options to reset the device:
  2. Once the device has been reset, restart the debugger.