Skip to content

Debugging concepts

This page describes some basic debugging concepts, such as debugging features that nRF Connect for VS Code offers and how to enable and start debugging.

About the debugger

VS Code comes with a built-in debugger to help troubleshoot problems. The main recommended tool for debugging with the nRF Connect SDK is the nRF Debug tool that uses Microsoft's debug adaptor.

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

You can customize launch and debug actions in VS Code. See the Advanced debugging techniques page for more information.

Debugger features

nRF Debug includes its own nRF Debug Panel View. Within the nRF Debug Panel View, two additional Panel Views are available: a Thread Viewer and a Memory Viewer. nRF Debug also features a Peripherals View in the Debug Sidebar.

Thread Viewer

The Thread Viewer shows information about specific threads in your application, when applicable. The threads are listed in the order that they were started. Their state is only updated when the debugger is stopped. While the device is running, the View is frozen. Any state in the table is stale until execution is stopped again. See the Panel Views page for more about its features.

Memory Viewer

The Memory Viewer shows the memory content on your device. You can review different Regions of memory data by clicking on the different tabs across the top of the View. See the Panel Views page for more about its features.

You can also add a custom memory section to the Memory Viewer, which functions as a shortcut view of the configured memory address.

Peripherals View

The Peripherals View appears in the Debug Sidebar when debugging has started. This View shows a memory map of peripherals from your device's SVD file and displays the values of their registers and fields. This View is unique to the extension's debugger nRF Debug.

See the Sidebar View UI page for more details about this View.

Enabling debugging

To enable debugging, 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:

  • 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.

Enabling debugging after building

If you forgot to enable debugging 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 debugging by clicking the Debug Application icon, start debugging by using Run -> Start Debugging or by pressing F5.

Debugging options

The are two options listed in the Actions View for debugging with the extension:

  • Debug, which uses the recommended nRF Debug tool.
  • Debug with Ozone, which is meant for J-Link.

Note

If you don't see the Ozone option, run nRF Connect: Debug with Ozone through the Command Palette Ctrl+Shift+P. VS Code will notify you that no Ozone is found. Click Configure path... to provide the path to the Ozone executable file and restart the application.

Note

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, either by running the nRF Connect: Recover Board command or by clicking the Recover icon in the Connected Devices View. Once the device has been reset, restart the debugger.

See the the VS Code debugging documentation for additional information.

Starting debugging

To start debugging with nRF Debug, click on Debug in the Actions View. The debugging toolbar appears at the top of the screen to let you control the debugging process. You also gain access to Debugging Views and the extension-exclusive nRF Debug Panel View.

If you have added a debugging launch configuration, you can also start debugging by clicking on Run and Debug from the Activity Bar.

Debugging 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.