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

Before generating, ensure required images are built (see Advanced 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

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: 25.11.0
Platform: ATM34xx-5 (atm34 family, rev-5)
Board: ATMEVK_3430e_YQN_5
LoadRram image=(size=169984,content=b'xS\x000%<\x01\x10'...) region_start=0x10000 region_size=0x7e800 address=0x10000000 extrainfo=APP
CmdExtend image=(size=794,content=b'ROM_ADDR'...) type=txt extrainfo=LAYOUT_MAP extrainfo=LAYOUT_MAP
$

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]

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.

  • 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.

Generate Archive File with Sysbuild

SB_CONFIG_ATM_ARCH enable to generate .atm file with all the built images by sysbuild (see Sysbuild and Flash).

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

Note

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