Atmosic Archive Tool

Overview

The Atmosic Archive Tool is used to bundle multiple binaries into a single archive (.atm) file with metadata such as SDK version, device information, and more.

The .atm file is available as a standalone archive file, can unpack the archive file and download the binaries to a device by Atmosic MP or Flash Programming tools or Archive tool directly.

The west extension command atm_arch is provided to allow users to generate the .atm archive file through a variety of sub commands.

Attention

Zephyr sysbuild is the preferred method to generate the archive. The steps in this document are provided for historical reference and advanced commands (erasing and loading user data). See Sysbuild and Flash

Python Requirements

The following setup procedures are not required when using atmoautil (see OpenAir Utility).

The Atmosic Archive Tool using a Google protobuf file, atm_isp.proto to define the metadata structure to generate the python code directly.

The atm_isp.proto protobuf file is built from openair\tools\scripts\atm_isp.proto and the generated python code can be found under openair\tools\scripts\atm_isp_python.

To generate the python code from atm_isp.proto file requires protobuf and grpcio-tools Python packages. (Do not using protoc to avoid compatible issue with generated python code)

To install with the OpenAir requirements file which includes the installation of protobuf and grpcio-tools Python packages:

pip install -r openair/scripts/requirements.txt

To generate the python code from atm_isp.proto according to current protobuf and grpcio-tools Python package will be done automatically with west atm_arch command.

Use the command below to manually re-generate, if needed.

python -m grpc_tools.protoc --proto_path=openair\tools\scripts --python_out=openair\tools\scripts\atm_isp_python atm_isp.proto

Note

  • This operation may uninstall existing protobuf packages and reinstall the latest versions compatible with your environment.

  • Python 3.11 is not compatible with grpcio-tools. It is recommended to use Python 3.10, Python 3.12 or a later version.

If needed, create a symbolic link or use a Python virtual environment:

For Linux:

sudo ln -s $(which python3) /usr/bin/python

For Windows:

mklink "C:\Path\To\Python\python3.exe" "C:\Path\To\Python\python.exe"

Note

On Windows:

  • you can use where python3 to locate the path of the Python executable.

  • Ensure that the symlink or Python installation directory is included in the system PATH environment variable, or place the symlink in a directory that is already in the PATH.

West atm_arch Commands

Use the following command to view usage details:

west atm_arch --help

Generate Archive File with Sysbuild

By adding -DSB_CONFIG_ATM_ARCH=y to sysbuild test items, sysbuild can generate .atm archive file (see Sysbuild and Flash).

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

west atm_arch individual commands as shown in next section can still be used to produce an archive file with various configuration options, for images built via Sysbuild. However, note that Sysbuild generated objects typically will reside under build/<APP>/zephyr. This is different from individual west build generated objects that are under build/<BOARD>/<APP>/zephyr sub directory. Do the appropriate substitution as required.

Note

Refer to sysbuild options (Atmosic Sysbuild Options) for detail.

Generate Archive File using individual west build commands (without sysbuild)

Before generating, ensure required images are built (see West Build and Flash).

Required parameters:

  • BOARD Atmosic device (see board).

  • APP Sample application build directory.

  • APP_NAME Name of the application.

Optional parameters:

  • MCUBOOT Build directory for MCUboot.

  • ATMWSTK_PATH Path to the BLE Stack (default: openair/modules/hal_atmosic/<soc>/drivers/ble).

  • ATMWSTK Fixed Wireless Stack choice of CPD200 (see Atmosic BLE Stack).

  • soc ATM33/e and ATM34/e series of Atmosic devices are supported. See soc.

Note

Optional parameters depend on the images generated by west build.

With Fixed BLE Stack

When west build with a fixed BLE stack (see Atmosic BLE Stack), the BLE Stack ELF file must be included in the archive.

To generate with BLE Stack ELF file:

--atmwstk_file <ATMWSTK_PATH>/atmwstk_<ATMWSTK>.elf

Note

the BLE Stack ELF file will be converted to binary automatically. And this requires the environment variable ZEPHYR_SDK_INSTALL_DIR to MUST be set.

With MCUboot

With fixed BLE Stack ELF:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.signed.bin \
--mcuboot_file build/<BOARD>/<MCUBOOT>/zephyr/zephyr.bin \
--atmwstk_file <ATMWSTK_PATH>/atmwstk_<ATMWSTK>.elf

Without fixed BLE Stack ELF:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.signed.bin \
--mcuboot_file build/<BOARD>/<MCUBOOT>/zephyr/zephyr.bin

Without MCUboot

Without fixed BLE Stack ELF:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \

Without BLE Stack ELF and Secure Debug enabled:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \
--sec_dbg_enable

With Factory or Setting Data

With factory data file:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \
--factory_data_file build/<BOARD>/<APP>/zephyr/zephyr_factory.bin

With setting data file:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \
--storage_data_file build/<BOARD>/<APP>/zephyr/zephyr_settings.bin

Adding Extra Erase or Program Commands

Erase entire RRAM and flash before programming:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \
--erase_all

Erase customized RRAM and flash regions:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \
--erase_flash=0x203000,0x1000 \
--erase_rram=0x7F000,0x800

Program a user binary:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>/<APP>/zephyr/zephyr.bin \
--load_bin=user_demo.bin,0x200000

Append a user binary to an existing archive using --append and -i:

west atm_arch --append \
-i <BOARD>_<APP_NAME>.atm \
-o new_<BOARD>_<APP_NAME>.atm \
-p build/<BOARD>/<APP>/zephyr/partition_info.map \
--load_bin=user_demo.bin,0x200000

Show and Flash Archive File

Show archive information:

west atm_arch -i <BOARD>_<APP_NAME>.atm --show

Sample output:

$ west atm_arch -i ATMEVK-3430e-YQN-5_beacon.atm --show
MPR start: 0, size: 0, lock_size: 0
OTA support: 0
Secure debug enabled: 0
Secure boot enabled: 0
SDK version: 26.03.0
Platform: ATM34xx-5 (atm34 family, rev-5)
Board: ATMEVK_3430e_YQN_5
EraseRram region_start=0x8e000 region_size=0x1000 base_address=0x10000000
LoadRram image=(size=126352,content=b'\xe8Z\x000m\x11\x02\x10'...) region_start=0x1c000 region_size=0x71000 address=0x10000000 extrainfo=APP
CmdExtend image=(size=902,content=b'ROM_ADDR'...) type=txt extrainfo=LAYOUT_MAP extrainfo=LAYOUT_MAP

For applications built with XIP (Execute In Place) or a split-image configuration, the archive contains additional entries reflecting the separate placement of the bootloader, fast-code, and the main application across RRAM and Flash:

Sample output (XIP / split image):

$ west atm_arch -i ATMEVK-3430e-YQN-5_smp_svr.atm --show
MPR start: 0, size: 0, lock_size: 0
OTA support: 0
Secure debug enabled: 0
Secure boot enabled: 0
SDK version: 26.03.0
Platform: ATM34xx-5 (atm34 family, rev-5)
Board: ATMEVK_3430e_YQN_5
EraseRram region_start=0x8e000 region_size=0x1000 base_address=0x10000000
LoadRram image=(size=67779,content=b'=\xb8\xf3\x96\x00\x00\x00\x00'...) region_start=0x1c000 region_size=0x72000 address=0x10000000 extrainfo=SIGNED_SPE_FASTCODE
LoadFlashNvds image=(size=10291,content=b'=\xb8\xf3\x96\x00\x00\x00\x00'...) region_start=0x0 region_size=0xc5000 extrainfo=APP
LoadRram image=(size=33480,content=b'\x18w\x010=,\x01\x10'...) region_start=0x10000 region_size=0xc000 address=0x10000000 extrainfo=MCUBOOT
CmdExtend image=(size=1374,content=b'ROM_ADDR'...) type=txt extrainfo=LAYOUT_MAP extrainfo=LAYOUT_MAP

Understanding the output:

  • MPR start, size, lock_size — Memory Protection Region (MPR) configuration. A start and size of 0 indicate no MPR is configured; non-zero values define a protected memory region and the size of the locked (write-protected) sub-region within it.

  • OTA support — Indicates whether Over-The-Air firmware update is enabled (1) or disabled (0).

  • Secure debug enabled — Indicates whether secure debug access is enabled (1) or disabled (0).

  • Secure boot enabled — Indicates whether secure boot verification is enabled (1) or disabled (0).

  • SDK version — The Atmosic SDK version used when the archive was created.

  • Platform — The target hardware platform.

  • Board — The target board identifier as defined in the Zephyr board configuration.

  • EraseRram — Erases a specific RRAM region before any programming takes place:

    • region_start — Offset within RRAM of the region to erase.

    • region_size — Size in bytes of the region to erase.

    • base_address — Base address of the RRAM memory-mapped space.

  • LoadRram — Describes a binary image to be programmed into RRAM:

    • size — Size of the binary payload in bytes.

    • content — A preview of the first few bytes of the binary data.

    • region_start — Offset within the RRAM region where programming begins.

    • region_size — Total size of the RRAM region allocated for this image.

    • address — Absolute memory-mapped address at which the image will be written.

    • extrainfo — Label indicating the role of the image (e.g., APP for the application binary, SIGNED_SPE_FASTCODE for the signed SPE fast-code image, MCUBOOT for the MCUboot bootloader).

  • LoadFlashNvds — Loads an image into the Flash region. In an XIP configuration, the main application binary resides in Flash and is executed in place from there rather than being copied to RRAM at boot:

    • size — Size of the application binary in bytes.

    • content — A preview of the first few bytes.

    • region_start — Offset within the Flash region where the image is written.

    • region_size — Total size of the Flash region allocated for this image.

    • extrainfo — Role of the image (e.g., APP for the main application).

  • CmdExtend — Describes an extended command entry bundled in the archive:

    • size — Size of the payload in bytes.

    • content — A preview of the first few bytes.

    • type — Payload format: txt for plain-text, script for a Tcl/shell script, or binary for raw binary data.

    • extrainfo — Label indicating the purpose of the entry (e.g., LAYOUT_MAP for the partition layout map used by flash programming tools).

Flash archive to device:

west atm_arch -i <BOARD>_<APP_NAME>.atm \
--openocd_pkg_root <OPENOCD_PKG_ROOT> --burn

or:

west atm_arch -i <BOARD>_<APP_NAME>.atm \
--openocd_pkg_root <OPENOCD_PKG_ROOT> --burn [--device <DEVICE_ID>] [--jlink] [--dl] [-f]

Where:

  • --device <DEVICE_ID> Serial number of the programmer (see serial).

  • --jlink Specify if using a J-Link interface. If omitted, the FTDI interface is assumed.

  • --dl Specify if using a Download Board (DL) interface.

  • -f Specify if using fast load to speed up the flash process.

  • OPENOCD_PKG_ROOT Root path for OpenOCD (default: openair/modules/hal_atmosic).

Note

If both --device and --jlink are omitted, the J-Link interface is assumed by default.

Erase first before flash archive to device:

west atm_arch -i <BOARD>_<APP_NAME>.atm \
--openocd_pkg_root <OPENOCD_PKG_ROOT> --burn [erase options]

Where:

  • erase options:

    • --erase_all Erase entire RRAM and flash before programming.

    • --erase_flash_all Erase entire flash before programming.

    • --erase_rram_all Erase entire RRAM before programming.