Skip to main content

Flashing an application onto the Icarus

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:

NOTE

The Actinius Programmer that was available for use in the nRF Connect for Desktop is now deprecated. Please use the Actinius I/O Serial Programmer instead.

Flashing through J-Link can be done in 2 different ways: directly from VS Code using the nRF Connect SDK extension, or with the West meta-tool. Flashing through Serial/USB and MCUBoot can be performed using the Actinius I/O Serial Programmer or the mcumgr utility.

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:

filenamedescription
zephyr.hexThe firmware application. This image is generally not used for nRF9160 development.
merged.hexThe firmware application along with the 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_update.binBinary of the firmware application that can be used for firmware updates, either FOTA or via cable (Serial / USB). This image can be flashed using the Actinius I/O Serial Programmer or the Mcumgr utility.

All the Icarus boards can be programmed using a Segger J-Link programmer. To flash an application onto the Icarus through this method you will need:

  • A J-Link programmer. E.g. the on-board J-Link on the nRF5340 development kit
  • In the case of the Icarus IoT Board v2 (i.e. Feather form-factor) a TC2030-CTX-NL TagConnect cable is needed to connect the J-Link programmer to the Icarus

The image below shows how an Icarus IoT Board v2 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.

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.

  1. Choose and download an Icarus sample application from the samples section.
  2. Open VS Code and click on the nRF connect icon in the left sidebar.
  3. Build the application if you haven't already (follow the guide on building an application for the Icarus).
  4. Connect the J-Link programmer to your computer. When connected, it will show up in the connected devices tab of VS Code.
  5. Power the Icarus by connecting it to your computer.
  6. 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.
  7. 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:

  1. 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.
  2. Select your COM port.
  3. 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.

  1. Connect the J-Link programmer to your computer. West will automatically detect the J-Link programmer.
  2. Power the Icarus by connecting it to your computer.
  3. 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).
  4. 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:

#PartitionDescription
1boot_partitionPartition that stores MCUBoot itself
2image_0_primary_partitionPrimary partition slot for the user application image
3image_0_secondary_partitionSecondary partition slot for the user application image
4scratch_partitionThe 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, all the Icarus boards come pre-programmed with MCUBoot. To build an MCUBoot-compatible user application, 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 which can then be flashed onto the Icarus using the mcumgr utility.

Flashing the application through mcumgr and MCUBoot:

  1. Build your own application or download an Icarus sample application from the samples section. Make sure that the application is built with the CONFIG_BOOTLOADER_MCUBOOT=y option.
  2. Open a command prompt and navigate to the build directory of your application, where the app_update.bin image is located ($ cd <path-to-sample-dir>/build/zephyr/)
  3. Connect the Icarus to your computer using the USB-connector or baseboard depending on the board type.
  4. 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.
  5. Flash the image onto the Icarus using the following command:
$ 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).

NOTE

The applications provided in the Actinius I/O Serial 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.

caution
(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:

  1. Add the following 2 files in the project root folder where the prj.conf resides (right click and save file):
  1. 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")
  1. 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 I/O Serial Programmer​

The Actinius I/O Serial Programmer is a module of Actinius I/O that can be used to flash your Icarus with pre-built applications and samples or your own custom binaries. It is compatible with Chrome, Chromium, Edge, Opera and it doesn't require any software to be installed to your computer.

Flashing the application:

  1. Login to Actinius I/O and click on "Serial Programmer"
  2. Connect your device and select the device type from the drop-down menu
  3. Select a pre-built application from the list or add your own app_update.bin
  4. Click the Write button to flash.
  5. Follow the instructions on the screen to put your board into MCUBoot mode.

The board will be flashed with the firmware application. Once flashing is finished, press the reset button on your board to start the application.

Last updated on