Programming an application

For simplicity, this guide will refer to both samples and applications as “applications”.

To program the output build files to your device, which in most of the cases will be zephyr.hex or merged.hex, use the steps for the development environment.

Before you program a device in nRF Connect for VS Code, you need to set up a build configuration, which is part of Building an application.

Complete the following steps to program the application:

  1. Connect the development kit to your PC using a USB cable.

  2. Power on the development kit.

  3. Make sure you are familiar with Hardware-specific programming steps.

  4. Open the nRF Connect extension in Visual Studio Code by clicking its icon in the Activity Bar.

  5. In the extension’s Actions View, click on Flash. If you have more than one device connected, select the device to program.

    You can select several devices of the same type to program them with the same build configuration.

    If the build system considers the build incomplete, using this action also triggers a rebuild before flashing.

For instructions about programming with nRF Connect for VS Code, see How to flash an application.

If you want to program with custom options or scripts, read about Binding custom tasks to actions in the extension documentation.

For information about how to flash and erase in nRF Connect for VS Code, read about the Application-specific flash options.

The flash command programs all cores by default, both in nRF Connect for VS Code and on the command line. If you want to program only one selected core, use west flash on the command line and specify the domain.

Selecting west runner

Starting with the nRF Connect SDK v3.0.0, all Nordic Semiconductor boards are using the nRF Util as the default runner for the west flash command. This change ensures that the programming process is consistent across all boards. See the build system section in the v3.0.0 migration guide for more information.

Note

The west debug command is not affected by this change of the default runner.

Runners are Zephyr-specific Python classes that wrap Zephyr’s flash and debug host tools and integrate them with west and the Zephyr build system to support west flash and related commands. Runners supported on a board are determined by the board.cmake file in the board folder, for example this one. In particular, the following include lines enable them, with the first <runner> listed becoming the default runner:

include(${ZEPHYR_BASE}/boards/common/<runner>.board.cmake)

For more information about runners, see the Zephyr documentation: Flash and debug support and Flashing: west flash.

If you want to change the runner used by west flash, you can use one of the following options:

  • Specify the runner permanently in your application’s CMakeLists.txt file:

    set(BOARD_FLASH_RUNNER nrfjprog)

  • Specify the runner for a single command:

    west flash -r nrfjprog

In either case, make sure you have the required tools installed on your system. nRF Util is part of the nRF Connect SDK toolchain bundle. For -r nrfjprog, you need the archived nRF Command Line Tools.

To see which runners are available for your board, run the following command:

west flash --context

The output will include lines like the following:

available runners in runners.yaml:
  nrfutil, nrfjprog, jlink, pyocd, openocd
default runner in runners.yaml:
  nrfutil

Hardware-specific programming steps

Some hardware has platform-specific requirements that must be met before you program the device. For additional information, check the user guide for the hardware platform that you are using.

For example, if you are working with an nRF9160 DK, you need to select the correct position of the board controller switch SW10 before you program the application to your development kit. Programming to Thingy:91 also requires a similar step, but using a different switch (SW2).

Programming the nRF52840 Dongle

To program the nRF52840 Dongle instead of a development kit, follow the programming instructions in nRF52840 Dongle or use the Programmer app.

Programming the nRF54H20 DK

To program the nRF54H20 DK, follow the programming instructions in the nRF54H20 device guide. Programming the nRF54H20 DK with the nRF Connect SDK version earlier than v3.0.0 requires installing the nrfutil device command for the west flash command to work with this device. Starting with the nRF Connect SDK v3.1.0, the nrfutil device command is part of the nRF Connect SDK toolchain bundle and you get it when you Install the nRF Connect SDK code and toolchain.

Optional programming parameters

You can customize the basic west flash command in a variety of ways. The following are most common in the nRF Connect SDK. For more options, see Zephyr’s Flashing: west flash.

Programming without --erase

As an alternative to the recommended west flash --erase, you can also clear only those flash memory pages that are to be overwritten with the new application. With such approach, the old data in other areas will be retained.

To erase only the areas of flash memory that are required for programming the new application, use the following command:

west flash
Programming with --recover

Recovering a device typically refers to the process of resetting it to a known, working state, often by erasing and reprogramming its memory. This is usually done in the following cases:

  • The device is not functioning correctly.

  • The device is using a readback protection, such as the Access port protection mechanism (AP-Protect), offered by several Nordic Semiconductor SoCs or SiPs supported in the nRF Connect SDK. In such a case, you might get an error similar to the following message:

    ERROR: The operation attempted is unavailable due to readback protection in
ERROR: your device. Please use --recover to unlock the device.

Use the following command to recover your device:

west flash --recover

This command erases all user-available non-volatile memory and disables the readback protection mechanism, if enabled.

The west flash --recover command uses one of the following background commands:

  • nrfjprog --recover for devices from nRF52, nRF53, and nRF91 Series.

  • nrfutil device recover for devices from nRF54H and nRF54L Series. For more information about how nrfutil device recover works, see the nRF Util documentation.