Skip to content

Getting Started

Install HeliosAOT python package: helios-aot

You can install helios-aot with pipx, pip, or uv.

Using pipx is the recommended way to install helios-aot as it allows installing and running python apps in isolated environments. Upon installation, helios-aot will be available in your PATH.

  • Install helios-aot: pipx install git+ssh://git@github.com/AmbiqAI/helios-aot.git@main
  • Upgrade helios-aot: pipx upgrade helios-aot
  • Invoke helios-aot: helios-aot --help
  • Remove helios-aot: pipx uninstall helios-aot
pip install git+https://github.com/AmbiqAI/helios-aot.git#egg=helios-aot

uv add "helios-aot @ git+https://github.com/AmbiqAI/helios-aot.git"

Permissions Warning

Before installing HeliosAOT, you must be granted permission to the repository. Please reach out to the Ambiq AI team to request access or support.

Install HeliosAOT CLI Binary

Alternatively, you can install a self-contained CLI binary for your OS. This is a convenient way to get started without needing to install Python or any dependencies.

Requirements

Software

Check the project's pyproject.toml file for a list of up-to-date Python dependencies. Note that the installation methods above will install all required dependencies.

Firmware

The generated C inference module can be export for either Zephyr or neuralSPOT. The dependencies for each target are:

CLI Usage

Once installed, HeliosAOT can be used from the command line. The main entry point is helios-aot, which can be run as follows:

$ helios-aot --help

usage: helios-aot [-h] <command> ...

positional arguments:
  <command>
    convert   Convert a LiteRT model to standalone C inference module.

options:
  -h, --help  show this help message and exit

Let's take a look at the convert command:

$ helios-aot convert --help

usage: helios-aot convert [-h] [--path PATH] [--model-path PATH] [--output-path PATH] [--module-name TEXT] [--module-type [neuralspot|zephyr]] [--prefix TEXT] [--memory-planner TEXT] [--operator-attributes [TEXT ...]] [--include-test | --no-include-test] [--subgraph INT] [--model-version TEXT]
                          [--verbose INT] [--log-file TEXT]

options:
  -h, --help            show this help message and exit
  --path PATH           Path to yaml configuration
  --model-path PATH     Path to liteRT file (default: model.tflite)
  --output-path PATH    Base path for output module. Can also be a zip file. (default: output.zip)
  --module-name TEXT    Name used for module (default: helios_aot_nn)
  --module-type [neuralspot|zephyr]
                        Module type (default: neuralspot)
  --prefix TEXT         Prefix added to sources to provide unique namespace (default: aot)
  --memory-planner TEXT
                        Memory planner strategy (default: greedy)
  --operator-attributes [TEXT ...]
                        Operator attributes
  --include-test        Include test case (default: False)
  --no-include-test
  --subgraph INT        Subgraph index (default: 0)
  --model-version TEXT  Model version (default: v1.0.0)
  --verbose INT         Verbosity level (default: 1)
  --log-file TEXT       Optional log file path

Example: Convert Anomaly Detection Model

In this example, we will convert a LiteRT model to a C inference module using the helios-aot CLI. Specifcally, we will convert the Anomaly detection model (ad01_int8.tflite) from MLPerf Tiny benchmark.

Step 1: Download the Model

First, we need to download the LiteRT model. You can use wget or any other tool to download the model file.

$ wget \
  -O ad01_int8.tflite \
  https://raw.githubusercontent.com/mlcommons/tiny/master/benchmark/training/anomaly_detection/trained_models/ad01_int8.tflite

Step 2: Convert the Model

Now, we can use the helios-aot CLI to convert the model. The following command will convert the model and generate a C module.

$ helios-aot convert \
    --model-path ad01_int8.tflite \
    --module-name ad01-int8 \
    --prefix ad01 \
    --output-path . \
    --verbose 1

INFO     Started AOT conversion
INFO     Step: Initializing module…
INFO     Step completed ✔
INFO     Step: Fusing and transforming operators…
INFO     Step completed ✔
INFO     Step: Planning memory allocation via greedy…
INFO     Step completed ✔
INFO     Step: Generating source code…
INFO     Step completed ✔
INFO     Step: Exporting zephyr module…
INFO     Step completed ✔
INFO     Step: Generating documentation…
INFO     Step completed ✔
INFO     AOT conversion completed

This will generate a C inference module in ./ad01-int8 with the following files:

./ad01-int8
├── LICENSE.txt
├── README.md
├── includes-api
│   ├── ad01_fully_connected_0.h
│   ├── ad01_fully_connected_1.h
│   ├── ad01_fully_connected_2.h
│   ├── ad01_fully_connected_3.h
│   ├── ad01_fully_connected_4.h
│   ├── ad01_fully_connected_5.h
│   ├── ad01_fully_connected_6.h
│   ├── ad01_fully_connected_7.h
│   ├── ad01_fully_connected_8.h
│   ├── ad01_fully_connected_9.h
│   └── ad01_model.h
├── module.mk
└── src
    ├── ad01_fully_connected_0.c
    ├── ad01_fully_connected_1.c
    ├── ad01_fully_connected_2.c
    ├── ad01_fully_connected_3.c
    ├── ad01_fully_connected_4.c
    ├── ad01_fully_connected_5.c
    ├── ad01_fully_connected_6.c
    ├── ad01_fully_connected_7.c
    ├── ad01_fully_connected_8.c
    ├── ad01_fully_connected_9.c
    └── ad01_model.c

3 directories, 25 files

By default, the tool will generate a neuralSPOT module. Next, we will show how to generate a Zephyr module. Before doing this, let's place the arguments into a YAML file to simplify the command line.

cat << 'EOF' > ad01-int8.yaml
# ad01-int8.yaml
model_path: ad01_int8.tflite
module_name: ad01-int8
module_type: zephyr
prefix: ad01
output_path: .
verbose: 1
EOF

Notice that the module_type is set to zephyr. Now we can run the convert command again:

$ helios-aot convert --path ad01-int8.yaml

INFO     Started AOT conversion
...
INFO     AOT conversion completed

This will generate a Zephyr module in ./ad01-int8 with the following files:

./ad01-int8
├── CMakeLists.txt
├── LICENSE.txt
├── README.md
├── includes-api/
├── src/
└── zephyr
    └── module.yaml

4 directories, 28 files

The generated module can be used in a Zephyr project. The CMakeLists.txt file contains the necessary configuration to build the module. The zephyr/module.yaml file contains the necessary configuration to integrate the module into a Zephyr project.

Next Steps