Output build files (image files)

The building process produces each time an image file.

The image file can refer to an executable, a program, or an ELF file. As one of the last build steps, the linker processes all object files by locating code, data, and symbols in sections in the final ELF file. The linker replaces all symbol references to code and data with addresses. A symbol table that maps addresses to symbol names is created. This table is used by debuggers. When an ELF file is converted to another format, such as HEX or binary, the symbol table is lost.

Depending on the application and the SoC, you can use one or several images.

The nRF Connect SDK build system places output images in the <build folder>/zephyr folder.

Common output build files

The following table lists build files that can be generated as output when building firmware for supported board targets. The table includes files for single-core and multi-core programming scenarios for both Visual Studio Code and command-line building methods. Which files you are going to use depends on the application configuration and not directly on the type of SoC you are using. The following scenarios are possible:

  • Single-image - Only one firmware image file is generated for a single core.

  • Multi-image - Two or more firmware image files are generated for a single core. For more details about this scenario, see Multi-image builds.

  • Multi-core - Two or more firmware image files are generated for two or more cores.

File

Description

Programming scenario

zephyr.hex

Default full image. In a multi-image build, several zephyr.hex files are generated, one for each image.

  • Programming board targets with NSPE or single-image.

  • Testing DFU procedure with nrfjprog (programming directly to device).

merged.hex

The result of merging all zephyr.hex files for all images for a core in a multi-image build. Used by Nordic Semiconductor’s board targets in single-core multi-image builds. In multi-core builds, several merged_<image_name>.hex fields are generated, where <image-name> indicates the core.

  • Programming multi-core application.

  • Testing DFU procedure with nrfjprog (programming directly to device).

merged_domains.hex

The result of merging all merged.hex files for all cores or processing environments (merged.hex for the application core and merged.hex or zephyr.hex for the network core).

  • Programming SPE-only and multi-core board targets.

  • Testing DFU procedure with nrfjprog (programming directly to device).

tfm_s.hex

Secure firmware image created by the TF-M build system in the background of the Zephyr build. It is used together with the zephyr.hex file, which is intended for the Non-Secure Processing Environment (NSPE). Located in build/tfm/bin.

Programming SPE-only and multi-core board targets.

app_update.bin

Application core update file used to create dfu_application.zip for multi-core DFU. Can also be used standalone for a single-image DFU. Contains the signed version of the application. This file is transferred in the real-life update procedure, as opposed to HEX files that are transferred with nrfjprog when emulating an update procedure. Compatible with MCUboot.

DFU process for single-image board targets and the application core of the multi-core board targets.

app_signed.hex

HEX file variant of the app_update.bin file. Can also be used standalone for a single-image DFU. Contains the signed version of the application. Compatible with MCUboot.

Programming single-image board targets and the application core of the multi-core board targets.

mcuboot_secondary_app_update.bin

Secondary slot variant of the app_update.bin file. Compatible with MCUboot in the direct-xip mode.

DFU process for single-core board targets.

mcuboot_secondary_app_signed.hex

Secondary slot variant of the app_signed.hex file. Compatible with MCUboot in the direct-xip mode.

Programming single-core board targets.

net_core_app_update.bin

Network core update file used to create dfu_application.zip. This file is transferred in the real-life update procedure, as opposed to HEX files that are transferred with nrfjprog when emulating an update procedure.

DFU process for the network core of multi-core board targets.

dfu_application.zip

Zip file containing both the MCUboot-compatible update image for one or more cores and a manifest describing its contents.

DFU process for both single-core and multi-core applications.

matter.ota

Matter-specific OTA image that contains a Matter-compliant header and a DFU multi-image package that bundles user-selected firmware images.

DFU over Matter for both single-core and multi-core applications.

<file_name>.zigbee

Zigbee-specific OTA image that contains the Zigbee application with the Zigbee OTA header used for providing information about the image to the OTA server. The <file_name> includes manufacturer’s code, image type, file version, and comment (customizable by user, sample name by default). For example: 127F-0141-01020003-light_switch.zigbee.

DFU over Zigbee for both single-core and multi-core applications in the nRF Connect SDK v2.0.0 and later.

MCUboot output build files

Note

MCUboot’s direct-xip mode and the related CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT Kconfig option are currently supported only on the single-core devices such as the nRF52 Series. For more details, see the more information section of the Developing with nRF52 Series page.

File

Description

dfu_application.zip

Contains the following:

  • The MCUboot-compatible update image for one or more cores when MCUboot is not in the direct-xip mode and a manifest describing its contents (all related *.bin files and a manifest.json file).

  • The MCUboot-compatible update image for the primary and secondary slots when MCUboot is in the direct-xip mode and manifest describing its contents (all related *.bin files and a manifest.json file).

dfu_mcuboot.zip

Contains two versions of MCUboot linked against different address spaces corresponding to slot0 (s0) and slot1 (s1) and a manifest JSON file describing their MCUboot version number (MCUBOOT_IMGTOOL_SIGN_VERSION), nRF Secure Immutable Bootloader (NSIB) version number (FW_INFO), board type. This file can be used by FOTA servers (for example, nRF Cloud) to serve both s0 and s1 to the device. The device can then select the firmware file for the slot that is currently not in use. Created when the options CONFIG_SECURE_BOOT and CONFIG_BUILD_S1_VARIANT are set.

app_update.bin

Signed variant of the firmware in binary format (as opposed to HEX). It can be uploaded to a server as a FOTA image.

signed_by_mcuboot_and_b0_s0_image_update.bin

MCUboot update image for s0 signed by both MCUboot and NSIB. The MCUboot signature is used by MCUboot to verify the integrity of the image before swapping and the NSIB signature is used by NSIB before booting the image.

signed_by_mcuboot_and_b0_s1_image_update.bin

MCUboot update image for s1 signed by both MCUboot and NSIB. The MCUboot signature is used by MCUboot to verify the integrity of the image before swapping and the NSIB signature is used by NSIB before booting the image.

app_to_sign.bin

Unsigned variant of the firmware in binary format.

app_signed.hex

Signed variant of the firmware in the HEX format. This HEX file is linked to the same address as the application. Programming this file to the device will overwrite the existing application. It will not trigger a DFU procedure.

app_test_update.hex

Same as app_signed.hex except that it contains metadata that instructs MCUboot to test this firmware upon boot. As app_signed.hex, this HEX file is linked against the same address as the application. Programming this file to the device will overwrite the existing application. It will not trigger a DFU procedure.

app_moved_test_update.hex

Same as app_test_update.hex except that it is linked to the address used to store the upgrade candidates. When this file is programmed to the device, MCUboot will trigger the DFU procedure upon reboot.

signed_by_mcuboot_and_b0_s0_image_moved_test_update.hex

Moved to MCUboot secondary slot address space.

signed_by_mcuboot_and_b0_s0_image_test_update.hex

Directly overwrites s0.

mcuboot_secondary_app_update.bin

Secondary slot variant of the app_update.bin file intended for use when MCUboot is in the direct-xip mode. Created when the CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT Kconfig option is enabled.

mcuboot_secondary_app_signed.hex

Secondary slot variant of the app_signed.hex file intended for use when MCUboot is in the direct-xip mode. Created when the CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT Kconfig option is enabled.

mcuboot_secondary_app_test_update.hex

Secondary slot variant of the app_test_update.hex file intended for use when MCUboot is in the direct-xip mode. Created when the CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT Kconfig option is enabled.

mcuboot_secondary_app_to_sign.bin

Secondary slot variant of the app_to_sign.bin file intended for use when MCUboot is in the direct-xip mode. Created when the CONFIG_BOOT_BUILD_DIRECT_XIP_VARIANT Kconfig option is enabled.

Other output build files

The following table lists secondary build files that can be generated when building firmware, but are only used to create the final output build files listed in the table above.

File

Description

zephyr.elf

An ELF file for the image that is being built. Can be used for debugging purposes.

zephyr.meta

A file with the Zephyr and nRF Connect SDK git hashes for the commits used to build the application. If your working tree contains uncommitted changes, the build system adds the suffix -dirty to the relevant version field.

tfm_s.elf

An ELF file for the TF-M image that is being built. Can be used for debugging purposes.

manifest.json

Output artifact that uses information from the zephyr.meta output file.

dfu_multi_image.bin

Multi-image package that contains a CBOR manifest and a set of user-selected update images, such as firmware images for different cores. Used for DFU purposes by Matter and Zigbee protocols.

signed_by_b0_s0_image.bin

Intermediate file only signed by NSIB.

signed_by_b0_s1_image.bin

Intermediate file only signed by NSIB.