Sysbuild images

Sysbuild allows you to add additional images to your builds.

Enabling images 

To add an additional image using sysbuild, you must modify the central sysbuild configuration. This is typically done in a sysbuild.conf file within an application, which is a Kconfig fragment applied to the default sysbuild configuration when a project is configured.

Note

On the nRF54H20 SoC, do not use any SECURE_BOOT or MCUBOOT option. The nRF54H20 SoC boot sequence is based on the Secure Domain, and it cannot be disabled. For more information, see nRF54H20 boot sequence.

The following sysbuild Kconfig options can be used to enable images in a build:

Sysbuild Kconfig option	Description
`SB_CONFIG_SECURE_BOOT_APPCORE`	Enable secure boot for application core (or main core if device only has a single core).
`SB_CONFIG_BOOTLOADER_MCUBOOT`	Build MCUboot image.

The following sysbuild Kconfig options are also available for nRF53-based devices. These options determine whether the secure boot image is included on the network core and specify the image for the network core:

Sysbuild Kconfig option	Description
`SB_CONFIG_SECURE_BOOT_NETCORE`	Enable secure boot for network core.
`SB_CONFIG_NETCORE_EMPTY`	nRF Connect SDK empty network core image Empty firmware for multiple core SoCs.
`SB_CONFIG_NETCORE_HCI_IPC`	Zephyr hci_ipc Bluetooth image HCI IPC.
`SB_CONFIG_NETCORE_RPC_HOST`	nRF Connect SDK rpc_host Bluetooth image Bluetooth: Host for nRF RPC Bluetooth Low Energy.
`SB_CONFIG_NETCORE_802154_RPMSG`	Zephyr 802.15.4 image IEEE 802.15.4 over RPMsg.
`SB_CONFIG_NETCORE_IPC_RADIO`	nRF Connect SDK ipc_radio image IPC radio firmware.
`SB_CONFIG_NETCORE_NONE`	No network core image.

The following sysbuild Kconfig options are available when MCUboot is configured in firmware loader mode: These options specify the image for the firmware loader:

Sysbuild Kconfig option	Description
`SB_CONFIG_FIRMWARE_LOADER_IMAGE_SMP_SVR`	Include SMP server as firmware loader image.

Adding custom images 

Note

The Partition Manager is a component in the nRF Connect SDK and is responsible for handling the memory partitioning at build time.

This functionality is in the process of being deprecated and replaced by Zephyr’s default devicetree-based memory partitioning. It is recommended that all new designs using Nordic devices, excluding the nRF91 Series devices, are to be built with DTS instead of Partition Manager. Partition Manager will be removed from the nRF Connect SDK by the end of 2026 from the main branch.

For more information on how to configure partitions using DTS and how to migrate your existing configuration to DTS, see the following pages:

Custom images can be added directly to a project (or board) or to a Zephyr module, making them accessible to multiple projects.

Adding to a single project 

To add an image to a single project, you need a sysbuild.cmake file in the root folder of your project to incorporate the image into the project. If the image selection is optional, a Kconfig.sysbuild file in the root folder of your project is also required to include Kconfig options for the sysbuild configuration. If the image selection is mandatory, the Kconfig.sysbuild file can be omitted.

kconfig.sysbuild file:

config MY_APP_IMAGE_ABC
    bool "Include ABC image"
    depends on SOC_SERIES_NRF53
    default y if BOARD_NRF5340DK_NRF5340_CPUAPP
    help
      Will include the ABC image in the build, which will...

source "$(ZEPHYR_BASE)/share/sysbuild/Kconfig"

sysbuild.cmake file

if(SB_CONFIG_MY_APP_IMAGE_ABC)
  ExternalZephyrProject_Add(
    APPLICATION ABC
    SOURCE_DIR "<path_to_application>"
    BUILD_ONLY true   # This will build the application and not flash it, this **must** be used when building additional images to a core (not the primary image) when using Partition Manager, as the main application for each core will flash a merged hex file instead
  )
endif()

This method can be used to add a new image to the existing board target.

Adding custom network core images

To add an image for a different board target (like for the network core of the nRF5340 SoC), you must use a different syntax. This can be handled using the following approach:

kconfig.sysbuild file:

menu "Network core configuration"
    depends on SUPPORT_NETCORE

config SUPPORT_NETCORE_ABC
    bool
    default y

choice NETCORE
    prompt "Netcore image"
    depends on SUPPORT_NETCORE && !EXTERNAL_CONFIGURED_NETCORE

config NETCORE_ABC
    bool "ABC"
    help
      Use ABC image as the network core image.

endchoice

if !NETCORE_NONE

config NETCORE_IMAGE_NAME
    default "abc" if NETCORE_ABC

config NETCORE_IMAGE_PATH
    default "$(ZEPHYR_MY_MODULE_MODULE_DIR)/<image_path>" if NETCORE_ABC

endif # !NETCORE_NONE

endmenu

source "$(ZEPHYR_BASE)/share/sysbuild/Kconfig"

sysbuild.cmake file - This file is optional and should be used only if specific custom configurations are required for the application.

if(SB_CONFIG_NETCORE_ABC)
  # Project can optionally be configured here if needed

  # This will add a Kconfig fragment file, named `my_extra.conf` from the application directory
  add_overlay_config(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.conf)
  # This will add a devicetree overlay file, named `my_extra.dts` from the application directory
  add_overlay_dts(${SB_CONFIG_NETCORE_IMAGE_NAME} ${SB_CONFIG_NETCORE_IMAGE_PATH}/my_extra.dts)
  # This will set a bool Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
  set_config_bool(${SB_CONFIG_NETCORE_IMAGE_NAME} CONFIG_MY_CUSTOM_CONFIG y)
  # This will set a string (or numeric) Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
  set_property(TARGET ${SB_CONFIG_NETCORE_IMAGE_NAME} APPEND_STRING PROPERTY CONFIG "CONFIG_FOO=my_custom_value\n")
endif()

Adding custom firmware loader images

You can add custom firmware loader images similarly to how nRF5340 network core images are incorporated. This can be handled using the following approach:

kconfig.sysbuild file:

menu "Firmware loader configuration"
    depends on MCUBOOT_MODE_FIRMWARE_UPDATER

config SUPPORT_FIRMWARE_LOADER_ABC
    bool
    default y

choice FIRMWARE_LOADER
    prompt "Firmware loader image"
    depends on MCUBOOT_MODE_FIRMWARE_UPDATER

config FIRMWARE_LOADER_IMAGE_ABC
    bool "ABC"
    help
      Use ABC image as the firmware loader image.

endchoice

if !FIRMWARE_LOADER_IMAGE_NONE

config FIRMWARE_LOADER_IMAGE_NAME
    default "abc" if FIRMWARE_LOADER_IMAGE_ABC

config FIRMWARE_LOADER_IMAGE_PATH
    default "$(ZEPHYR_MY_MODULE_MODULE_DIR)/<image_path>" if FIRMWARE_LOADER_IMAGE_ABC

endif # !FIRMWARE_LOADER_IMAGE_NONE

endmenu

source "$(ZEPHYR_BASE)/share/sysbuild/Kconfig"

sysbuild.cmake file - This file is optional and should be used only if specific custom configurations are required for the application.

if(SB_CONFIG_FIRMWARE_LOADER_IMAGE_ABC)
  # Project can optionally be configured here if needed

  # This will add a Kconfig fragment file, named `my_extra.conf` from the application directory
  add_overlay_config(${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} ${SB_CONFIG_FIRMWARE_LOADER_IMAGE_PATH}/my_extra.conf)
  # This will add a devicetree overlay file, named `my_extra.dts` from the application directory
  add_overlay_dts(${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} ${SB_CONFIG_FIRMWARE_LOADER_IMAGE_PATH}/my_extra.dts)
  # This will set a bool Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
  set_config_bool(${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} CONFIG_MY_CUSTOM_CONFIG y)
  # This will set a string (or numeric) Kconfig option in the image (note: sysbuild forces this setting, it cannot be overwritten by changing the application configuration)
  set_property(TARGET ${SB_CONFIG_FIRMWARE_LOADER_IMAGE_NAME} APPEND_STRING PROPERTY CONFIG "CONFIG_FOO=my_custom_value\n")
endif()

Adding to a single board

You can place the same code as in the Adding to a single project section, without the Zephyr sourcing, in a board directory. This enables the use of those images for any sysbuild-based project being built for that board:

Kconfig.sysbuild:

config MY_APP_IMAGE_ABC
    bool "Include ABC image"
    depends on SOC_SERIES_NRF53
    default y if BOARD_NRF5340DK_NRF5340_CPUAPP
    help
      Will include the ABC image in the build, which will...

sysbuild.cmake:

if(SB_CONFIG_MY_APP_IMAGE_ABC)
  ExternalZephyrProject_Add(
    APPLICATION ABC
    SOURCE_DIR "<path_to_application>"
    BUILD_ONLY true   # This will build the application and not flash it, this **must** be used when building additional images to a core (not the primary image) when using Partition Manager, as the main application for each core will flash a merged hex file instead
  )
endif()

Adding through a Zephyr module

To add images in a Zephyr module, create a folder within the module to hold the Kconfig.sysbuild and (optionally, if needed) CMakeLists.txt files. Then, add this folder to the Zephyr module file:

build:
  sysbuild-cmake: sysbuild  # Only needed if a sysbuild CMakeLists.txt file is being added
  sysbuild-kconfig: sysbuild/Kconfig.sysbuild

The CMakeLists.txt file is the same as the sysbuild.cmake file from the previous examples. The Kconfig.sysbuild file is the same as the file from the previous examples but without the Zephyr sourcing. When images are configured, these additional images will be available from sysbuild and can be used in any project within the tree.

Kconfig.sysbuild:

menu "Network core configuration"
    depends on SUPPORT_NETCORE

config SUPPORT_NETCORE_ABC
    bool
    default y

choice NETCORE
    prompt "Netcore image"
    depends on SUPPORT_NETCORE && !EXTERNAL_CONFIGURED_NETCORE

config NETCORE_ABC
    bool "ABC"
    help
      Use ABC image as the network core image.

endchoice

if !NETCORE_NONE

config NETCORE_IMAGE_NAME
    default "abc" if NETCORE_ABC

config NETCORE_IMAGE_PATH
    default "$(ZEPHYR_MY_MODULE_MODULE_DIR)/<image_path>" if NETCORE_ABC

endif # !NETCORE_NONE

endmenu

Editing sysbuild images and domains in nRF Connect for VS Code 

nRF Connect for VS Code provides a GUI for editing sysbuild images and domains. See the How to work with sysbuild domains page in the extension documentation for more information.

Sysbuild images

Enabling images

Adding custom images

Adding to a single project

Adding custom network core images

Adding custom firmware loader images

Adding to a single board

Adding through a Zephyr module

Editing sysbuild images and domains in nRF Connect for VS Code

Enabling images 

Adding custom images 

Adding to a single project 

Editing sysbuild images and domains in nRF Connect for VS Code 