Atmosic Sysbuild Options

This guide explains how to configure sample.yaml files for sysbuild operations in Zephyr applications, with specific focus on Atmosic device configurations including MCUboot, TrustZone, DFU, OTA, XIP, and ATM archive generation.

Table of Contents

Basic Structure
Common Configuration Options
Atmosic-Specific Configurations
MCUboot Configurations
TrustZone Configurations
DFU and OTA Configurations
Channel Sounding (CS) Configurations
XIP (Execute-in-Place) Configurations
ATM Archive Generation
Complete Examples
Building with Sample.yaml

Basic Structure

A sample.yaml file defines test configurations for applications. Here’s the basic structure:

sample:
  description: Brief description of the sample
  name: Sample Name
common:
  sysbuild: true  # Enable sysbuild for all tests
  harness: console
  harness_config:
    type: one_line
    regex:
      - "Expected output pattern"
  tags:
    - tag1
    - tag2
tests:
  test.name.configuration:
    tags:
      - specific_tags
    extra_args:
      - SB_CONFIG_OPTION=value
    extra_configs:
      - CONFIG_OPTION=value

Note

When using west build for your Zephyr project, note the critical difference in precedence between configuration files and command-line arguments.
The configuration options passed via the command line (appended after –) using the -D flag e.g., west build – -DCONFIG_MY_SETTING=y will not overwrite settings that are already explicitly defined in Kconfig fragment files.

Configuration options that applies to MCUboot or SPE (if configured) can be passed by specifying domain name before option. e.g. - mcuboot_CONFIG_FOO=y or - spe_CONFIG_FOO=y

Common Configuration Options

Sysbuild Options

sysbuild: true - Enable sysbuild for the test
SB_CONFIG_SPE=y - Enable Secure Processing Environment (SPE) image

Harness Configuration

harness: console
harness_config:
  type: one_line          # or multi_line
  regex:
    - "Boot pattern"
    - "Success pattern"

Atmosic-Specific Configurations

SPE (Secure Processing Environment)

extra_args:
  - SB_CONFIG_SPE=y  # Enable SPE image build

BLE Stack Options

extra_args:
  # PD50 Link Controller
  - SB_CONFIG_ATMWSTK_PD50=y

  # CPD200 Link Controller
  - SB_CONFIG_ATMWSTK_CPD200=y

Common Extra Configs

extra_configs:
  # Logging levels
  - CONFIG_LOG_DEFAULT_LEVEL=3              # Info level logging
  - CONFIG_LOG_DEFAULT_LEVEL=1              # Error level logging

  # Assertions and debugging
  - CONFIG_ASSERT=n                         # Disable assertions
  - CONFIG_ATM_PLF_DEBUG=n                  # Disable platform debug

Note

extra_configs apply only to given application. It won’t be applied to MCUBOOT or the SPE (if configured).

DTS Extra CPP Flags

extra_args:
  # Pass DTS preprocessor flags to all images
  - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_STORAGE_SIZE=0x1000;-DDFU_IN_FLASH"

  # XIP configuration
  - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_APP_FLASH_XIP"

  # MCUboot scratch size for overwrite mode
  - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_MCUBOOT_SCRATCH_SIZE=0"

MCUboot Configurations

Basic MCUboot Setup

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y

MCUboot Modes

Swap with Scratch

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y

Overwrite Only

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y

Signature Types

# ECDSA P-256 (most common for Atmosic)
- SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y

# RSA signatures
- SB_CONFIG_BOOT_SIGNATURE_TYPE_RSA=y

# ED25519 signatures
- SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519=y

# No signature (hash only)
- SB_CONFIG_BOOT_SIGNATURE_TYPE_NONE=y

TrustZone Configurations

With TrustZone

tests:
  app.with.trustzone:
    extra_args:
      - SB_CONFIG_SPE=y

MCUboot without TrustZone (Default)

tests:
  app.mcuboot.no.trustzone:
    extra_args:
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y

DFU and OTA Configurations

Bluetooth OTA

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
  - EXTRA_CONF_FILE="basic_ota_bt.conf"

Note

External flash is always required for DFU operations. The secondary slot (slot1) for MCUboot is always located in external flash.

Serial DFU

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
  - EXTRA_CONF_FILE="${ZEPHYR_OPENAIR_MODULE_DIR}/doc/dfu/overlay-serial-dfu.conf"
  - EXTRA_DTC_OVERLAY_FILE="app_uart0.overlay"

Combined BT OTA + Serial DFU

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
  - EXTRA_CONF_FILE="basic_ota_bt.conf;${ZEPHYR_OPENAIR_MODULE_DIR}/doc/dfu/overlay-serial-dfu.conf"

Channel Sounding (CS) Configurations

Basic Channel Sounding

extra_args:
  - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_STORAGE_SIZE=0x1000"
  - EXTRA_CONF_FILE="basic_cs_pd50.conf"
extra_configs:
  - CONFIG_ATM_CS=y
  - CONFIG_ATM_LL_HEAP_SIZE=34816

XIP (Execute-in-Place) Configurations

Flash XIP

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
  - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_APP_FLASH_XIP"
  - mcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=2

Flash XIP with Overwrite

extra_args:
  - SB_CONFIG_BOOTLOADER_MCUBOOT=y
  - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
  - SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y
  - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_APP_FLASH_XIP;-DATM_MCUBOOT_SCRATCH_SIZE=0"
  - mcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=2
  - mcuboot_CONFIG_MCUBOOT_VERIFY_IMG_ADDRESS=n

ATM Archive Generation

Enable ATM Archive Generation

extra_args:
  - SB_CONFIG_ATM_ARCH=y  # Generate .atm file additionally

ATM Archive with Erase Options

extra_args:
  - SB_CONFIG_ATM_ARCH=y
  - SB_CONFIG_ATM_ARCH_ERASE_ALL=y          # Erase all flash and RRAM
  - SB_CONFIG_ATM_ARCH_ERASE_FLASH_ALL=y    # Erase all flash
  - SB_CONFIG_ATM_ARCH_ERASE_RRAM_ALL=y     # Erase all RRAM

Storage Erase (Default)

extra_args:
  - SB_CONFIG_ATM_ARCH=y
  - SB_CONFIG_ATM_ARCH_ERASE_STORAGE=y      # Erase factory and settings storage (default)

Note

Python 3.11 is not supported for ATM archive generation. Use Python 3.10 or 3.12.
The generated .atm file will be located at: build/<BOARD>_<APPLICATION>.atm
SB_CONFIG_ATM_ARCH_ERASE_STORAGE is enabled by default unless SB_CONFIG_ATM_ARCH_ERASE_ALL is set.

Complete Examples

Example 1: Basic Application without MCUboot

sample:
  description: Basic Atmosic Application
  name: Basic App
common:
  sysbuild: true
  harness: console
  harness_config:
    type: one_line
    regex:
      - "Application started"
tests:
  app.basic.atm:
    tags:
      - atm33
      - atm34
      - no_mcuboot
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_ATMWSTK_CPD200=y

Example 2: MCUboot with OTA Support

sample:
  description: Application with MCUboot and OTA
  name: MCUboot OTA App
common:
  sysbuild: true
  harness: console
  harness_config:
    type: one_line
    regex:
      - "Bluetooth initialized"
tests:
  app.mcuboot.ota:
    tags:
      - atm33
      - atm34
      - mcuboot
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
      - EXTRA_CONF_FILE="basic_ota_bt.conf"

Example 3: Multi-Configuration Sample

sample:
  description: Multi-configuration sample with various options
  name: Multi Config Sample
common:
  sysbuild: true
  harness: console
  harness_config:
    type: one_line
    regex:
      - "System ready"
tests:
  # Basic configuration without MCUboot
  app.basic:
    tags:
      - atm33
      - atm34
      - no_mcuboot
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_ATMWSTK_CPD200=y

  # MCUboot with swap scratch
  app.mcuboot.swap:
    tags:
      - atm33
      - atm34
      - mcuboot
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
      - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_STORAGE_SIZE=0x1000"

  # MCUboot with overwrite only (RRAM only)
  app.mcuboot.overwrite:
    tags:
      - atm33
      - mcuboot
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_OVERWRITE_ONLY=y

  # Flash XIP configuration
  app.mcuboot.flash_xip:
    tags:
      - atm34
      - mcuboot
      - flash_xip
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
      - SB_ATM_DTS_EXTRA_CPPFLAGS="-DATM_APP_FLASH_XIP"
      - mcuboot_CONFIG_UPDATEABLE_IMAGE_NUMBER=2

  # Serial DFU configuration
  app.serial_dfu:
    tags:
      - atm33
      - atm34
      - mcuboot
    extra_args:
      - SB_CONFIG_SPE=y
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
      - EXTRA_CONF_FILE="${ZEPHYR_OPENAIR_MODULE_DIR}/doc/dfu/overlay-serial-dfu.conf"
      - EXTRA_DTC_OVERLAY_FILE="app_uart0.overlay"
      - SB_ATM_DTS_EXTRA_CPPFLAGS="-DDFU_IN_FLASH"

Example 4: ATM Archive Generation

sample:
  description: Sample with ATM archive generation
  name: ATM Archive Sample
common:
  sysbuild: true
  harness: console
  harness_config:
    type: one_line
    regex:
      - "Archive ready"
tests:
  app.with.archive:
    tags:
      - atm33
      - atm34
      - mcuboot
    extra_args:
      - SB_CONFIG_BOOTLOADER_MCUBOOT=y
      - SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y
      - SB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y
      - SB_CONFIG_ATM_ARCH=y
      - SB_CONFIG_ATM_ARCH_ERASE_ALL=y

Building with Sample.yaml

Using Test Items

Build using specific test configurations defined in sample.yaml:

# Build with specific test item
west build -p always -b <BOARD> <APP_PATH> --sysbuild -T <test_item>

# Examples:
west build -p always -b <BOARD> openair/samples/hello_world --sysbuild -T samples.hello_world.atm

west build -p always -b <BOARD>@mcuboot openair/applications/multimode_consumer_tag --sysbuild -T applications.multimode_consumer_tag.atm.mcuboot.ota

Manual Configuration

Build with manual sysbuild options:

# Basic MCUboot build
west build -p always -b <BOARD>@mcuboot <APP_PATH> --sysbuild \
  -DSB_CONFIG_SPE=y \
  -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \
  -DSB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y \
  -DSB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y

# With ATM archive generation
west build -p always -b <BOARD>@mcuboot <APP_PATH> --sysbuild \
  -DSB_CONFIG_SPE=y \
  -DSB_CONFIG_BOOTLOADER_MCUBOOT=y \
  -DSB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y \
  -DSB_CONFIG_MCUBOOT_MODE_SWAP_SCRATCH=y \
  -DSB_CONFIG_ATM_ARCH=y

Building ATM Archive Files

Automatic Generation with Sysbuild

When SB_CONFIG_ATM_ARCH=y is enabled, the .atm file is additionally generated:

west build -p always -b <BOARD> <APP_PATH> --sysbuild -T <test_item> -DSB_CONFIG_ATM_ARCH=y

The generated .atm file will be located at: build/<BOARD>_<APPLICATION>.atm

This guide provides a comprehensive overview of configuring sample.yaml files for Atmosic devices with various sysbuild options. Refer to existing samples in the codebase for additional configuration examples.