vscode-nrf-connect

nRF Connect for Visual Studio Code

Nordic Semiconductor’s nRF Connect for Visual Studio Code extension turns VS Code into a complete IDE for developing applications for nRF91, nRF53 and nRF52 Series devices on Windows, macOS or Linux. This includes an interface to the compiler and linker, an RTOS-aware debugger, a seamless interface to the nRF Connect SDK, and a serial terminal.

Quick User Guide for nRF Connect for VS Code

Prerequisites

Before you use nRF Connect for VS Code for the first time, make sure your setup meets the prerequisites in this section.

Linux

  1. Install the nRF Connect SDK manually.

Note: Some Linux distributions, such as Ubuntu 20.04 LTS, require that you manually install the package libncurses5 as a dependency of arm-none-eabi-gdb.

Windows and macOS

We recommend installing the nRF Connect SDK through the Toolchain Manager, then adding the other required tools:

  1. Install nRF Connect for Desktop to access the Toolchain Manager.
  2. Through the Toolchain Manager, install the nRF Connect SDK and associated tools for Windows or macOS. You can update the SDK and toolchain separately.

All operating systems

For Linux, Windows and macOS:

Note: M1 is not currently supported in the extension, so M1-based Mac machines must run the Intel versions of the tools.

Once you have these tools installed, proceed to Getting started.

Getting started

The extension includes a walk-through on versions of VS Code 1.57 or greater that explains the fundamentals of how to use it. Alternatively, you can watch the walk-through videos directly from the YouTube playlist.

Installation

  1. In the VS Code editor, click on the Extensions tab in the left-hand toolbar, or click on View > Extensions from the top menu.
  2. Type 'nRF Connect for VS Code' in the search box.
  3. Click the Install button from the extension page and reload VS Code when prompted.

You can also find the extension by searching for 'nRF Connect for VS Code' in the VS Code Marketplace.

Setup

Set the default nRF Connect SDK and nRF Connect Toolchain in the Quick Setup feature located on the extension’s Welcome page. Access the Welcome page by either clicking on the Extensions tab and then Open Welcome Page, or use the nRF Connect: Welcome command available in the Command Palette (Ctrl+Shift+P or ++P).

Quick Setup for nRF Connect for VS Code

If you set up your environment using the Toolchain Manager, select one of the detected installations. Alternatively, browse to your manual installations using the Browse… option.

If the toolchain is installed on the system path, you can set the toolchain value to PATH. The extension checks if the required tools in the correct version are present.

After you set these values, they are saved in your User Settings, acting as a fallback if the current workspace does not override them. You can modify these later either by opening the Quick Setup feature again, or click through the following menu path and edit the Toolchain: Path and Topdir values.

Creating an application

  1. Click Create a new application from sample from either the Welcome page or the Welcome panel.

    Add a build configuration

  2. Choose the application type.

    • Freestanding applications require a preinstalled nRF Connect SDK.
    • Workspace applications use west workspace, which creates a dedicated copy of nRF Connect SDK for each application.
  3. Set the Application location to where you want your application to be copied.
  4. Type in a name for the application. This creates another directory in your Application location.
  5. By default, nRF Connect SDK is determined by the version you selected during setup. If you want to compile your application against a different version, install that version from the Toolchain Manager.
  6. For the Application template, click the Browse button to open the Sample Browser.
    1. Search for specific samples by typing into the search field, or filter specific parameters by clicking the filter icon.
    2. When you have found the sample you want to use, click Select and then click Create Application.
      • Note: Some samples in the nRF Connect SDK are currently not designed to work out-of-tree. You may need to manually configure your sample to work correctly in the extension.

Building an application

Setting up the build configuration

A build configuration is essentially a CMake build system, which compiles and links the application components into a single image.

  1. From the Applications panel in the extension, click on the Add build configuration icon next to your application.

    Add a build configuration

  2. Fill in the configuration options on the Generate Configuration screen.

    Configuration option Description
    Board Select the board that you want to work with.
    Configuration Enter the name of the application configuration file.
    Kconfig fragments Kconfig fragment selector
    Extra CMake arguments Enter additional CMake build arguments.
    Build directory name Enter the name for the build directory.
    Build after generating configuration The application is built after the configuration file is generated.
    Enable debug options Debugging features are enabled after the application is built.
  3. When you have finished configuring your build, click Generate config. You will know your configuration is complete when you see the build files appear in the build details panel.

    Build configuration files

Adding a custom board

If you have a custom board, follow these instructions during your build configuration setup after you have created an application.

  1. Click Create a new board from either the Welcome page or the Welcome panel.

  2. Enter your custom board information.
  3. After the board is created, select your custom board from the Generate Configuration screen.

Working with multiple applications

The extension lets you work with multiple applications without the need for a multi-root workspace. You can see the list of applications associated with the current workspace in the Applications view. An application can have several build configurations that represent different cmake build systems. At any given time, only one configuration, and thus application, is active. The name of the active configuration is indicated in the Applications view and the status bar.

Working with multiple applications

When opening a file in the editor or changing the active editor window, and the file is in an application’s directory, the active application will implicitly change. If the file belongs to a build directory, then the active configuration will change too.

Any folder from your working tree can be added as an application if it has either a prj.conf or sample.yaml file. Right-click on the folder and then Add Folder as Application.

Testing an application

Connecting to serial port or RTT in nRF Terminal

The nRF Terminal extension is an integrated serial port and RTT terminal. From the Connected Devices panel, click the button indicated in red to connect over RTT. Click the button indicated in green to connect to a device over serial port.

Connect to serial port in nRF Terminal

Alternatively, launch the Command Palette and run nRF Connect: Connect to serial port in nRF Terminal or nRF Connect: Connect to RTT in nRF Terminal.

Flashing an application

After you connect your board, click on the Flash option from the Actions panel. A small notification banner will appear in the bottom right corner of VS Code to display the progress and when the flash is complete.

After changing parameters in your application, click on Build from the Actions panel. If you have changed configuration files, then click Pristine Build instead of Build. Click Flash to flash to the board again.

Debugging an application

VS Code comes with a built-in debugger to help troubleshoot problems. The are two options listed in the Actions panel for debugging with the extension: Debug, which uses GDB, and Debug with Ozone.

  1. Click on Debug in the Actions panel.
  2. The debugging control bar will appear 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.

Settings and commands

Access the extension’s commands by opening the Command Palette (Ctrl+Shift+P or ++P) and typing nRF Connect.

For a full overview of settings and commands, click the Extensions tab > nRF Connect for VS Code. Then choose the Feature Contributions tab.

Additional settings information

nrf-connect.topdir is a west workspace for building freestanding applications. It is the parent directory of zephyr and is used as a fallback if the west topdir command can not be executed. It is the final fallback to the ZEPHYR_BASE environment variable.

nrf-connect.toolchain.path is the path of the toolchain installed by the Toolchain Manager and overrides {nrf-connect.topdir}/toolchain. If neither are set, the toolchain will be expected to be located on PATH.

Note: For nrf-connect.topdir and nrf-connect.toolchain.path, there is a variable substitution feature which replaces ${nrf-connect.sdk:VER} and ${nrf-connect.toolchain:VER} references with corresponding paths found in the CMake package registry that can be resolved by VER. For example, ${nrf-connect.sdk:1.5.1} will be resolved to the installation path of nRF Connect SDK v1.5.1.

nrf-connect.west.env is the configuration setting containing an object that will replace the west environment, as well as the special key $base. $base must either be "process", "terminal" or null, and will determine the initial environment. By default, $base is "terminal", which makes the extension pick up the platform-specific terminal environment. All other fields in this object will be added as environment variables, overriding any corresponding variables in the base environment.

{
  "$base": "process",
  "CUSTOM_ENV_VAR": "custom value",
  "OTHER_ENV_VAR": "another value",
}

Advanced features

Automatic IntelliSense configuration

The extension is able to automatically configure IntelliSense in the C/C++ for Visual Studio Code extension. The configuration is inferred by matching the current file in the editor to the build configuration and source tree it belongs to. The extension parses the build configuration, collects all the relevant compiler options, and configures IntelliSense for the current file.

Source files that are shared by different build configurations can be opened simultaneously. This is due to the structure and dependencies of an application source tree and the fact that you can work with multiple applications and build configurations in your workspace, e.g. nRF Connect SDK source files. In such cases, the extension tries to match the compiler options to the selected active application and build configuration.

If your settings contain C/C++ extension (C_Cpp.defaults.*) configurations, these might conflict or override the auto-configured settings. To check which settings are applied, we suggest using the C/C++: Log Diagnostics command from the Command Palette.

Custom launch and debug configurations

The extension provides its own task and debug configuration types.

The nrf-connect-build and nrf-connect-flash task types can be used for building and flashing a build configuration, respectively. The following task.json file shows the custom types with some of the accepted parameters.

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "nrf-connect-build",
			"config": "${workspaceFolder:hello_world}\\build_nrf52840",
			"runCmake": false,
			"problemMatcher": [
				"$gcc",
				"$cmake",
				"$kconfig",
				"$kconfig_syntax",
				"$kconfig_syntax_files",
				"$dts",
				"$dts_syntax"
			],
			"group": "build",
			"label": "nRF Connect: Build build_nrf52840 (active)"
		},
		{
			"type": "nrf-connect-flash",
			"config": "${workspaceFolder:hello_world}\\build_nrf52840",
			"snr": "683888634",
			"erase": false,
			"problemMatcher": [],
			"label": "nRF Connect: Flash build_nrf52840 (active)"
		}
	]
}

The nrf-connect debug configuration type wraps the Cortex-Debug extension, which sets up the required configuration parameters for the selected build configuration. The debug configuration type accepts all parameters supported by Cortex-Debug, so you can tweak the configuration for your specific setup.

To use the nRF Connect for VS Code debug configuration, open the Run menu in the top level menu bar, click Add configuration…, and choose nRF Connect. Alternatively, click the cogwheel icon in the top of the VS Code Debug sidebar view and add a debug configuration with the nrf-connect type.

The following example shows a launch.json file using the nrf-connect debug type.

{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "nrf-connect",
			"request": "launch",
			"name": "Launch active build configuration",
			"config": "${activeConfig}",
			"runToEntryPoint": "main",
			"preLaunchTask": "nRF Connect: Build active configuration"
		},
		{
			"name": "Launch build_nrf52840dk_nrf52840",
			"type": "nrf-connect",
			"request": "launch",
			"config": "c:\\Users\\joe\\workspace\\apps\\hello_world\\build_nrf52840",
			"runToEntryPoint": "main"
		}
	]
}

Terminal profile

The extension includes a terminal profile that is configured to work with west and the rest of the nRF Connect Toolchain and nRF Connect SDK environment. This can be accessed from the “Launch Profile…” dropdown list available in the terminal view. Alternatively, run the "nRF Connect: Create Shell Terminal" command. The version of nRF Connect SDK used will depend on the value of the nrf-connect.toolchain.path setting at the time the terminal was created. Changes to this value will not be picked up by existing terminal instances, and you will need to create a new terminal to use the new environment.

All changes to the terminal environment are limited to this profile, so the default integrated terminal profile will work as before.

Toolchain path resolution

The extension resolves paths to the build tools, such as west or cmake, using the nrf-connect.toolchain.path setting. These paths are then set in the PATH environment variable in the environment that is used to call west for actions such as building or flashing.

To allow for this, the cmake NCS_TOOLCHAIN_VERSION variable is set to NONE when calling west. This instructs the build system to look for the necessary tools on PATH rather than resolve the paths internally.

When pasting command line invocations of west from the integrated terminal to an external terminal, make sure that the tools available on PATH in the external terminal are the same as the tools indicated by nrf-connect.toolchain.path.

Controlling the west environment

On macOS and Linux, the official documentation for the nRF Connect SDK suggests that you add your environment variables, such as GNUARMEMB_TOOLCHAIN_PATH, in ~/.bashrc. Unfortunately, VS Code does not pick up environment variables added to this file, even when launching VS Code from a terminal.

To get around this issue, the extension will query Bash for its environment on Linux and macOS. This executes the ~/.bashrc file, as well as any other files that run when starting Bash. If any of these files execute behavior that you do not want, either check for $NRF_CONNECT_VSCODE in your Bash scripts, or change the nrf-connect.west.env setting.

Note: VS Code will pick up environment variables set in .profile. To disable this option while still being compatible with the terminal, move nRF Connect SDK-specific environment variables (such as ZEPHYR_TOOLCHAIN_VARIANT or GNUARMEMB_TOOLCHAIN_PATH) to .profile.

Creating device aliases

The extension supports creating names or aliases for connected devices so that you do not have to remember their serial numbers to interact with them. Create a device alias by right-clicking on the device in the Connected Devices panel and choosing Rename Device. To remove an alias, right-click on the device and choose Remove Device Alias.

In the example below, the device was renamed to the alias “Light Switch”.

Connected devices panel with device aliased to "Light Switch"

If you have created aliases using nRF Connect for Desktop, then the extension will use those and read and write to the same configuration file. If that configuration file does not exist, then aliases will be remembered by the extension. Aliases in the configuration file will take precedence over aliases in the extension memory.

Linking build configurations and devices

To save time, link a build configuration with a specific device. Actions on that build configuration that require a device to be selected, such as flashing, will then always be performed on that device.

To create a link, use the following steps:

  1. Click on the link icon that appears when you hover over a build configuration: Link build configuration and device icon

  2. If you have several devices connected, select the device you want to link from the drop-down list.

The build configuration and device will now be linked. The device icon and the labels of device-specific actions will change to confirm this: Linked build configuration and device

To unlink a build configuration from a device, click on the link icon again. Note that an individual build configuration can only be linked to one device, but a device may be linked to multiple build configurations.

Known issues

Feedback

Give us feedback in the Nordic DevZone.

License

See the LICENSE file for details.