.. _west_atm_arch-tool: 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 :ref:`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: .. code-block:: bash 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. .. code-block:: bash 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: .. code-block:: bash sudo ln -s $(which python3) /usr/bin/python For Windows: .. code-block:: bash 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: .. code-block:: bash west atm_arch --help Generate Archive File ********************* Before generating, ensure required images are built (see :ref:`advanced_build_and_flash`). Required parameters: - ``BOARD`` Atmosic device (see :ref:`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//drivers/ble**). - ``ATMWSTK`` Fixed Wireless Stack choice of FULL (see :ref:`Atmosic BLE Stack `). - ``soc`` ATM33/e and ATM34/e series of Atmosic devices are supported. See :ref:`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 :ref:`Atmosic BLE Stack `), the BLE Stack ELF file must be included in the archive. To generate with BLE Stack ELF file: .. code-block:: bash --atmwstk_file /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:** .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.signed.bin \ --mcuboot_file build///zephyr/zephyr.bin \ --atmwstk_file /atmwstk_.elf **Without fixed BLE Stack ELF:** .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.signed.bin \ --mcuboot_file build///zephyr/zephyr.bin Without MCUboot =============== **Without fixed BLE Stack ELF:** .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin **Without BLE Stack ELF and Secure Debug enabled:** .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin \ --sec_dbg_enable With Factory or Setting Data ============================ **With factory data file:** .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin \ --factory_data_file build/_ns//zephyr/zephyr_factory.bin **With setting data file:** .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin \ --storage_data_file build/_ns//zephyr/zephyr_settings.bin Adding Extra Erase or Program Commands ************************************** Erase entire RRAM and flash before programming: .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin \ --erase_all Erase customized RRAM and flash regions: .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin \ --erase_flash=0x203000,0x1000 \ --erase_rram=0x7F000,0x800 Program a user binary: .. code-block:: bash west atm_arch -o _.atm \ -p build/_ns//zephyr/partition_info.map \ --app_file build/_ns//zephyr/zephyr.bin \ --spe_file build///zephyr/zephyr.bin \ --load_bin=user_demo.bin,0x200000 Show and Flash Archive File *************************** Show archive information: .. code-block:: bash west atm_arch -i _.atm --show Flash archive to device: .. code-block:: bash west atm_arch -i _.atm \ --openocd_pkg_root --burn or: .. code-block:: bash west atm_arch -i _.atm \ --openocd_pkg_root --burn [--device ] [--jlink] Where: - ``--device `` Serial number of the programmer (see :ref:`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 :ref:`Sysbuild and Flash `). .. code-block:: bash west build -p always -b //ns --sysbuild -T -DSB_CONFIG_ATM_ARCH=y .. note:: Refer to sysbuild options (:ref:`Atmosic Sysbuild Options `) for detail.