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.

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.

  • SPE Build directory for Secure Processing Environment (SPE).

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

  • ATMWSTK Fixed Wireless Stack choice of FULL (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>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<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>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<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>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/zephyr/zephyr.bin

Without BLE Stack ELF and Secure Debug enabled:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/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>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/zephyr/zephyr.bin \
--factory_data_file build/<BOARD>_ns/<APP>/zephyr/zephyr_factory.bin

With setting data file:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/zephyr/zephyr.bin \
--storage_data_file build/<BOARD>_ns/<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>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/zephyr/zephyr.bin \
--erase_all

Erase customized RRAM and flash regions:

west atm_arch -o <BOARD>_<APP_NAME>.atm \
-p build/<BOARD>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/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>_ns/<APP>/zephyr/partition_info.map \
--app_file build/<BOARD>_ns/<APP>/zephyr/zephyr.bin \
--spe_file build/<BOARD>/<SPE>/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

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]

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.

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

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>//ns <APP> --sysbuild -T <test_item> -DSB_CONFIG_ATM_ARCH=y

Note

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