Flashing an application onto the Icarus

Last updated on: December 22, 2022

There is a variety of methods to flash a binary onto the Icarus. This guide shows you how to flash a binary onto the Icarus through:

Available binary files for nRF9160
Flashing an application using J-Link and TagConnect
Flashing an application using MCUBoot and USB
Flashing an application using the Actinius Programmer

Flashing through J-Link and TagConnect can be done in 3 different ways: with VS Code using the nRF Connect SDK extension, with the West meta-tool, and with the Segger Embedded Studio (not covered). Flashing through MCUBoot and USB requires you to use the mcumgr utility. Finally, the Actinius Programmer provides both methods through the nRF Connect for desktop program.

Available binary files for nRF9160

There is a range of binary files that are generated when building an application with Zephyr and the nRF Connect SDK. The table below describes the most used binaries and their differences:

filename	description
`zephyr.hex`	Contains the user application and the Zephyr RTOS. This image is generally not used for nRF9160 development.
`zephyr.bin`	Binary format of the `zephyr.hex` file.
`merged.hex`	Contains the user application, Zephyr RTOS, and bootloader(s) (there can be either one or multiple bootloaders in the image e.g. SPM + MCUBoot). This image can be flashed to the nRF9160 using a J-Link programmer and West.
`app_signed.hex`	Contains the user application and the Zephyr RTOS. This image can be flashed to the nRF9160 using the Actinius programmer.
`app_update.bin`	Binary format of the `app_signed.hex` file. This image can be flashed to the nRF9160 using the Mcumgr utility (mcumgr only accepts `.bin` files).

Flashing an application using J-Link and TagConnect

The Icarus can be programmed by using a J-Link programmer and a TagConnect cable. To flash an application onto the Icarus through this method you will need:

An Icarus
A J-Link programmer. E.g. the nRF5340 development kit
A TC2030-CTX-NL TagConnect cable

The image below shows how an Icarus and nRF5340 development kit are setup for programming. In this example, both boards are powered through the micro-USB ports.

Programming setup with a nRF5340 development kit as a programmer. The boards are connected through the TagConnect cable and are powered through the microUSB ports.

Flashing the application through VS Code:
Flashing an application through VS Code can currently only be done through a J-Link programmer. The nRF Connect SDK extension provides dedicated buttons in the GUI of VS Code to program a board.

Choose and download an Icarus sample application from the samples section.
Open VS Code and click on the nRF connect icon in the left sidebar.
Build the application if you haven't already (follow the guide on building an application for the Icarus).
Connect the J-Link programmer to your computer. When connected, it will show up in the connected devices tab of VS Code.
Power the Icarus by connecting it to your computer.
Plug the Tagconnect cable into the J-link programmer and press the Tagconnect pins onto the programming pads of the Icarus (see the datasheet for more information about the TagConnect programming pads). A purchase of the Icarus with the TagConnect cable will include a clip that can be used to secure the TagConnect cable to the Icarus without having to hold it.
Under the actions tab in VS Code, click on flash or erase and flash.

The Icarus will now be flashed with the new application. After programming, the board is reset automatically and the application is started. If the application provides serial output you can view it in VS Code through the nRF terminal extension:

Click on the nRF Terminal Disconnected button in the blue toolbar at the bottom of your screen. This will prompt you to select a serial port and baudrate.
Select your COM port.
Set the baudrate to 115200 Bd.

Flashing the application through West:
You can flash binaries to the Icarus through West after building your application. There are multiple binaries generated during building and they can be found in the build directory under \build\zephyr\. The binary used by West contains the user application, zephyr kernel, and bootloader(s). It is available in the following formats: merged.elf, merged.bin, and merged.hex format.

Connect the J-Link programmer to your computer. West will automatically detect the J-Link programmer.
Power the Icarus by connecting it to your computer.
Plug the Tagconnect cable into the J-link programmer and press the Tagconnect pins onto the programming pads of the Icarus (see the datasheet for more information about the TagConnect programming pads).
Flash the binary onto the Icarus using the following command:

$ west flash --verify

The flash command will automatically take the required binary and flash it to the Icarus. After programming, the board is reset automatically and the application is started.

Flashing an application using MCUBoot and USB

It is possible to program the nRF9160 on the Icarus through the USB-connector without the need of a J-Link programmer by using the MCUBoot bootloader. This is a bootloader that runs from flash and enables firmware upgrades without the need of programming pins. MCUBoot requires a certain partition structure in the flash to work. These partitions have been defined in the device-tree of the Icarus:

#	Partition	Description
1	boot_partition	Partition that stores MCUBoot itself
2	image_0_primary_partition	Primary partition slot for the user application image
3	image_0_secondary_partition	Secondary partition slot for the user application image
4	scratch_partition	The scratch slot. This partition is used for reliable image swapping when doing a firmware upgrade.

For more information on MCUBoot and its workings, check out the MCUBoot documentation.

Out-of-the-box the Icarus comes pre-programmed with the Actinius Asset Tracker (Production Firmware Bundle) which includes MCUBoot. To build an MCUBoot compatible user appilication, the application must be built with the CONFIG_BOOTLOADER_MCUBOOT=y option (can be set in prj.conf). This will generate an application update image named app_update.bin, with the correct memory offset for MCUBoot. The user application can be flashed onto the Icarus using the mcumgr utility, which can be found at:

$ cd C:/<user>/.nrfconnect-apps/external/actinius/node_modules/actinius-programmer/resources/utils/

It can be useful to add this path to your PATH variable so mcumgr can be used anywhere.

Flashing the application through mcumgr and MCUBoot:

Choose and download an Icarus sample application from the samples section.
Build the application if you haven't already. Make sure that the application is built with the CONFIG_BOOTLOADER_MCUBOOT=y option.
Open a command prompt.
Navigate to the location of the app_update.bin image:

$ cd <path-to-sample-dir>/build/zephyr/

Connect the Icarus to your computer using the USB-connector.
Press and hold the reset button. Then press the user button and release the reset button. Finally release the user button as well. This will put the Icarus in MCUBoot mode.
Flash the image onto the Icarus using the following command. Make sure you use a .bin file:

$ mcumgr image upload app_update.bin --conntype=serial --connstring="dev=<com-port>,baud=115200"

The <com-port> on Windows can be e.g. COM4. The board will now get flashed with the app_update.bin image. Press the reset button on the Icarus to start the application.

WARNING:
If you get an error saying: "Error: Access is denied" it means that mcumgr cannot access the COM-port on which your Icarus is connected. Make sure to close the port of the Icarus from all serial monitors on your computer (VS Code might automatically connect the serial monitor when the Icarus is connected to your PC).

Restoring MCUBoot on your board:
It might happen that you have previously programmed an application onto your board, using a J-Link programmer, that does not contain the MCUBoot bootloader. Building your application with the CONFIG_BOOTLOADER_MCUBOOT=y option, will include the MCUBoot bootloader. If this option is not enabled, your board will not run MCUBoot. This means you can only flash the board using a J-Link programmer and TagConnect cable.

To restore MCUBoot on your board, you can add the CONFIG_BOOTLOADER_MCUBOOT=y option to your application and rebuild it. After building, flash your board with the new application image (merged.hex). Alternatively, you can also re-program the board with the Asset Tracker (Factory Firmware Bundle). This firmware is available through the Actinius Programmer.

NOTE:
The applications provided in the Actinius Programmer use the default private key bundled with MCUBoot. If you change MCUBoot that comes pre-programmed on the board and use your own private key, you should keep using the same key to create and sign further updates otherwise MCUBoot will fail to start your update. If you wish to restore MCUBoot to the one provided by Actinius, just re-program the Asset Tracker (Factory Firmware Bundle) using a programmer.

(The following is only important for Icarus board versions < v2.0)

Different MCUboot versions and partition offsets:
If you are building an application with nRF Connect SDK v1.3.x or higher and your goal is to flash app_update.bin on an Icarus that came with the Asset Tracker Application v1.x.x, then the partition offsets for MCUBoot must be changed. SDK versions v1.3.x and up use different offsets for the MCUBoot partitions that are not compatible with the offsets of MCUBoot that comes shipped with Icarus versions < v2.0.

Your generated app_signed.hex image should use the old partition offsets. The application image can be made compatible by following these steps:

Add the following 2 files in the project root folder where the prj.conf resides (right click and save file):

Partition manager YAML file: pm_static.yml
MCUBoot config overlay file: mcuboot_overlay-rsa.conf

Insert the following lines into CMakeLists.txt, under the line "cmake_minimum_required..."

set(PM_STATIC_YML_FILE ${CMAKE_CURRENT_SOURCE_DIR}/pm_static.yml)
list(APPEND mcuboot_OVERLAY_CONFIG "${CMAKE_CURRENT_SOURCE_DIR}/mcuboot_overlay-rsa.conf")

Rebuild your application.

The pm_static.yml file sets all the partition offsets to the values used by the old MCUBoot version.

NOTE: The steps described above are not needed if you have flashed an application with a newer version of MCUBoot (nRF Connect SDK version > v1.3.x) onto your Icarus using a J-Link programmer.

Flashing an application using the Actinius Programmer

The Actinius Programmer is an application that can be used to flash images to your nRF-based device using either a J-Link programmer or MCUBoot. The application provides a GUI and a list of sample applications to choose from. A screenshot of the Actinius Programmer is shown in the image below:

Device selection menu. Select the J-Link programmer when flashing through J-Link and TagConnect. Select the Icarus board when flashing through MCUBoot.
Menu to select and add your custom binaries to flash through the Actinius Programmer.
Buttons for writing, erasing, resetting, and reading a connected device.
Enable programming through MCUBoot. Gets automatically checked when the Icarus board is selected as a device.
Sample applications for nRF-based Actinius boards. A different board can be selected on the right.
Memory map of the connected device. Only shows something when a device is connected through the J-Link programmer and TagConnect cable.
Memory map of the selected application to be flashed.
Console with messages for debugging.

Flashing the application:

Open the nRF Connect for Desktop program.
Open the Actinius Programmer.
Select your device from the drop-down menu. Select the J-Link programmer if flashing through J-Link and TagConnect. Select the actual board if flashing through MCUBoot.
Select a pre-built application from the list or add your own .hex image. Make sure you use the app_signed.hex image and not app_update.bin or merge.hex when flashing through MCUBoot. Only use the merge.hex when programming through a J-Link programmer.
Click the Write button to flash.
If flashing through MCUBoot, follow the instructions on the screen to put your board into MCUBoot mode.

The board will now be flashed with your application. You can follow the flashing process through the console which provides debug output. Press the reset button on your board to start the application.