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 |
|---|---|
|
Enable secure boot for application core (or main core if device only has a single core). |
|
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 |
|---|---|
|
Enable secure boot for network core. |
|
nRF Connect SDK empty network core image nRF5340: Empty firmware for network core. |
|
Zephyr hci_ipc Bluetooth image Bluetooth: HCI IPC. |
|
nRF Connect SDK rpc_host Bluetooth image Bluetooth: Host for nRF RPC Bluetooth Low Energy. |
|
Zephyr 802.15.4 image nRF IEEE 802.15.4: Serialization RPMsg. |
|
nRF Connect SDK multiprotocol_rpmsg Bluetooth and 802.15.4 image nRF5340: Multiprotocol RPMsg. |
|
nRF Connect SDK ipc_radio image IPC radio firmware. |
|
No network core image. |
Adding custom images
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:
config MY_APP_IMAGE_ABC
bool "Include ABC image"
depends on SOC_SERIES_NRF53X
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:
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:
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:
This file is optional and is only needed if custom configuration needs to be set on the application
if(SB_CONFIG_MY_APP_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_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_CUSTOM_STRING=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_NRF53X
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 via 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