Installation

heliaAOT runs on your development machine and turns a LiteRT .tflite model into C. Start with an isolated CLI installation; firmware libraries and board tools are needed later.

Install the compiler

uv

uv tool install helia-aot
helia-aot version

If the command is not on your shell’s path, run uv tool update-shell and open a new shell. Upgrade with uv tool upgrade helia-aot.

uvx

uvx helia-aot version

Use uvx helia-aot ... for the remaining commands in this walkthrough. Pin a release when reproducing a conversion: uvx helia-aot@<version> ..., with the version helia-aot version printed.

pip

python -m venv .venv
source .venv/bin/activate
python -m pip install helia-aot
helia-aot version

On Windows, activate with .venv\Scripts\activate. Upgrade with python -m pip install --upgrade helia-aot.

Source

Source installation requires access to the private heliaAOT repository. Use one of the package installation options above if you do not have repository access.

git clone https://github.com/AmbiqAI/helia-aot.git
cd helia-aot
uv sync --frozen
uv run helia-aot version

Use uv run helia-aot ... in this checkout. Record git rev-parse HEAD with a conversion you need to reproduce; the default branch can change.

An isolated tool installation does not make the Python API importable from another project environment. For API use, install helia-aot into that project’s environment; see the Python API guide.

Verify it

helia-aot --version
helia-aot --help

--version prints the same installed compiler version as helia-aot version and exits successfully without reading a conversion configuration or model. The version command identifies the installed compiler. Help lists version, convert and platforms, and the deprecated aliases list-targets and target-info, which are removed in 2.0. A successful version command checks the installation; it does not check your model or firmware toolchain.

The examples on this site use helia-aot. Substitute the launcher from your chosen tab consistently. When keeping a deployment record, save the version alongside the model, configuration and generated module.

What else you will need

Stage	Requirements
Read a target and convert	Python 3.11 or newer; the model and, for this walkthrough, its golden fixture
Build the walkthrough application	A Zephyr workspace supporting Apollo510, west, the Zephyr SDK and ns-cmsis-nn
Run on silicon	Apollo510 EVB, J-Link programming connection/software and a serial terminal

The next three pages need only the host installation. Other firmware formats are covered in Firmware integration.

The two version floors

The package requires Python 3.11 or newer and declares support for Python 3.11–3.14. TensorFlow is not required: conversion, including automatic golden data from LiteRT, runs on the ai-edge-litert dependency.

Generated modules require ns-cmsis-nn 7.47.0 or newer, from the ns-cmsis-nn releases. Upstream Arm CMSIS-NN is not supported: the generated header stops a build that finds it instead of ns-cmsis-nn. The generated aot_common.h enforces the module’s floor at compile time. An operator can require a newer release, which then raises the floor of the module it is in; no operator does today. A module converted for an MVE target plans layers for MVE: int8 convolution, depthwise and fully connected layers read weight sums, holding their biases, that only an MVE build reads, and int8 and int16 average pools get no scratch, which the DSP path of their kernels needs. So aot_common.h stops a build without ARM_MATH_MVEI. A layer whose kernel entry needs MVE, as some int16 convolutions do, stops such a build with #error in its own source file. Enable MVE (for example -mcpu=cortex-m55 with a hard or softfp float ABI, or CONFIG_ARMV8_1_M_MVEI on Zephyr) and link an MVE build of ns-cmsis-nn, or convert for the target you build for. The reverse holds too: a module converted for a target without MVE stops a build with ARM_MATH_MVEI when one of its layers would be planned differently with MVE, with another kernel entry, other scratch or weight sums, as int8 convolution and fully connected layers are. Layers planned the same either way, such as int8 max pooling, build for both. A compile-only check can define HELIA_AOT_SKIP_TARGET_CHECK, which lifts these checks; a build that defines it and runs the model gives wrong output, an error status or a crash. You need the library to build the emitted C, not to convert the model.

For the cmake and nsx module types, the generated CMakeLists.txt also reads the version from the linked library’s arm_nn_types.h and stops at configure time, naming both versions, when the library is older than the module needs. If it cannot find or read that header through the library target’s include directories, the compile-time check still applies. The version a module needs is recorded as generator.cmsis_nn_required in <prefix>_plan.json, for scripts that check a kernel library before building.

C language and toolchain requirements

Use a toolchain compatible with the complete firmware SDK and kernel library. The generated CMake target requests c_std_99, while generated headers also use features such as stdalign.h. The generated README calls for a target-compatible toolchain and distinguishes the C99 declaration from C11 host checks. A CMake language feature declaration alone is not a portability guarantee. Toolchains and build environments separates compatibility declarations from build and execution coverage.

After upgrading, regenerate the module and repeat its build and output check. Version requirements describes the version contract.