How to debug

The extension offers several options for debugging your application. The default option is to use the recommended nrf-connect debug type 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, select the Optimize for debugging optimization level when you are setting up a build configuration.

When you add a build configuration with this option selected, the following Kconfig 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, so make sure to fine-tune the stack sizes of your threads for debugging.

Note

By default, the nrf-connect.debugging.justMyCode setting hides the internal functions of Zephyr and the nRF Connect SDK in Call Stack. Change the setting to false in application settings if you want to see these internal functions.

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, go to the Optimization level drop-down menu.
4. In the menu, select Optimize for debugging.
5. 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 Optimize for debugging selected.

To work around this issue, generate the build configuration without Optimize for debugging selected. 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 the extension debug type

The extension comes with the nrf-connect debug type that is meant for debugging applications compatible with the nRF Connect SDK using the Visual Studio Code debugger. There are two default options to start debugging using this debug type:

• 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-specific nRF Debug Panel View.
• Click on Run and Debug from the Activity Bar if you have added a debugging launch configuration.

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 action. It allows you to start debugging with SEGGER Ozone, the J-Link multi-platform debugger and performance analyzer.

If you have Ozone installed, click the action 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 action 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:
   • Run the nRF Connect: Recover Board command.
   • Click the Recover icon in the Connected Devices View.
2. Once the device has been reset, restart the debugger.

How to attach the debugger to a running application

The extension lets you start the debugging process after you have flashed an application and the application is running on the device. This can be useful for example to debug issues without having to reflash the application when using the standard Debug action, or when you do not want to use Erase and Flash to Board to flash an application to a device with readback protection enabled.

Use the Attach Debugger to Target action from the Debug's More actions... menu.

Tip

You can also manually edit the launch.json file to launch the debugger against a debugging server that is already running.

How to access peripherals from the debug console

During debugging, you can access peripherals of your device listed in the Peripherals View. The peripherals can only be accessed if the respective types are included in the build.

You can access the peripherals from the Debug Console in the Panel View using the pattern NRF_<peripheral_name>. For example, to print the PWM0 peripheral, use the following command:

-exec print NRF_PWM0

If the device does not use the given type, trying to access it on the device will result in an error stating that the given type does not exist.