Debugging an application

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

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

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.

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 for J-Link.

Note

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

sudo apt install libncurses5

To use debugging with nRF Debug:

1. Click on Debug in the Actions View.

2. The debugging control bar appears at the top of the screen to let you control the debugging process.

   Control	Description
   Start/Continue	Starts or continues the debugging process
   Step over	Steps over a function
   Step in	Steps into a function
   Step out	Steps out of a function
   Restart	Restarts the debugging process
   Stop	Stops the debugging process

3. Click on the left side of any line of code to set or remove a breaking point.

See the the VS Code debugging documentation for additional information.

Change the default debugger

If you want to use Cortex-Debug, you can change the debugging settings in the Extension Settings. When the Cortex-Debug option is selected, the Debug button in the Actions View will use this to debug applications.

Enabling Cortex-Debug

To enable Cortex-Debug:

1. Click on the Extensions icon from the Activity Bar.

2. Find the nRF Connect for VS Code and click on the Settings icon on the bottom right corner of the extension.

3. Click on Extension Settings.

4. Scroll down to Nrf-connect > Debugging: Backend.

5. In the dropdown menu, click on Cortex-Debug.

Debugging Views

There are several debugging Views available in the Sidebar to help you examine the debugging process.

Sidebar Views

The following are Views found in the Sidebar while debugging.

Variables

The Variables View shows variables in the current scope and organizes them into local, global, and static sections.

Watch

The Watch View shows the output of variables you have selected to watch.

To start watching a variable:

1. Click and drag the mouse cursor to highlight the variable in your code.
2. Right-click and choose Add to Watch.
3. Click the Start/Continue button in the debugging control bar to watch the debugger go through the code until it stops at a variable breakpoint. The output of the code displays in the Watch View.

Call Stack

The Call Stack lists all of the available threads and indicates which ones are running. It also includes the call stack for each individual thread that is running.

Breakpoints

All breakpoints that you have set in the code are listed in the Breakpoints View.

Peripherals

The Peripherals View shows a memory map of peripherals from your device's SVD file and displays the values of their registers and fields.

Panel Views

The following are Panel Views found exclusively when debugging the nRF Debugger Panel View:

Thread

The Thread Viewer shows information about specific threads in your application. The threads are listed in rows by Address, in the order in which they were started. Hover your mouse over the items in the State or User Options column to reveal a tooltip that describes the indicated binary value.

Memory

The Memory Viewer shows the memory content on your device. You can review different Regions of memory data by clicking on the different buttons in the first row.

Debug troubleshooting

Check the following troubleshooting topics if you have problems with running the debugger.

Debugging does not work

There is a known issue where debugging may not work when 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 times out

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.