First conversion

Compile a known model before adapting the process to your own. The result of this step is a Zephyr module for Apollo510 EVB, with a generated numerical test and a memory report. Everything here runs on the host.

Get a model

Create a working directory and run the remaining host commands from it:

mkdir kws-first
cd kws-first
BASE=https://media.githubusercontent.com/media/AmbiqAI/helia-model-zoo/329f6b7417638f3938dbc945fcb8345d4eeeea50/audio/mlperf-tiny/kws_ref
curl -fL -o kws_ref.tflite "$BASE/model.tflite"
curl -fL -o golden.npz "$BASE/golden.npz"

These are the MLPerf Tiny keyword-spotting model and golden fixture (Apache-2.0) from helia-model-zoo at a fixed commit. A helia-aot checkout has the same two files in examples/first-model/kws_ref/. Verify the bytes:

Verify the downloaded model and fixture

python - <<'PYTHON'
import hashlib
from pathlib import Path

expected = {
    "kws_ref.tflite": "aeea436800704fce17b17292e4412630ad856e9d777c044c64ef748a880bd0ae",
    "golden.npz": "434290baa67ce60cf6e7b0d3f5539acae92d3c0890d9f30636d16b3762402f13",
}
for name, wanted in expected.items():
    actual = hashlib.sha256(Path(name).read_bytes()).hexdigest()
    if actual != wanted:
        raise SystemExit(f"{name}: SHA-256 mismatch: {actual}")
    print(f"{name}: SHA-256 verified")
PYTHON

Stop on a mismatch and check the download and model revision. Do not replace the expected hash just to accept different bytes.

This model has one int8 input shaped [1, 49, 10, 1] and one int8 output shaped [1, 12]. The NPZ stores input_0 and output_0 for that pair. It is already model input data, so no microphone capture or audio preprocessing is needed for the generated test.

Convert it

Save this complete configuration as kws.yaml in the same working directory:

model:
  path: kws_ref.tflite
  name: kws_ref
module:
  path: ./out
  name: kws_ref
  prefix: aot
  type: zephyr
platform:
  name: apollo510_evb
memory:
  dump_residency_json: true
test:
  enabled: true
  golden_data: golden.npz
  tolerance: 1.0
  num_iterations: 1
  skip_verification: false


        $
        helia-aot convert --path kws.yaml
      
        
        Analyze → Plan → Emit
      
        
        Model: kws_ref | Module: zephyr | Target: apollo510_evb
      
        
        Output: out/kws_ref/

This is a shortened illustration, not a captured conversion. The actual Results summary includes the model’s arena sizes and generated output path.

The explicit golden data supplies the stimulus and expected output; this path does not need to invoke a host reference interpreter. The test allows an absolute difference of one stored int8 output step. Keep that threshold fixed while investigating a mismatch; it is not an instruction to accept whatever difference appears.

CLI flags can override the file for a run, for example --platform.name apollo510_evb. Use YAML for structured rule lists. See Configuration for field names and flag spellings.

The repository also has a runnable first-model example using the same hashed model/fixture pair. Its output format is CMake; the saved configuration above selects Zephyr for this walkthrough.

What the console prints

Conversion progresses through Analyze, Plan and Emit. Read the Results summary for kws_ref, zephyr, apollo510_evb, the arena sizes and the output path. Exact counts and timing can vary with the compiler version. When an option could make this model faster on this target, the Results also list it under Optimization hints, with its measured gain, its accuracy cost and the YAML that sets it. The choice made for every operator is in <prefix>_plan.json next to the module, and the facts behind the hints are in <prefix>_report.json; see Performance and accuracy options.

Check that these files now exist:

out/kws_ref/README.md
out/kws_ref/includes-api/aot_model.h
out/kws_ref/includes-api/aot_test_case.h
out/kws_ref/src/aot_test_case.c
out/kws_ref/zephyr/module.yml
out/kws_ref/aot_residency.json
out/kws_ref/aot_plan.json
out/kws_ref/aot_report.json

A successful conversion means source was emitted. It has not compiled or run the generated C. Save the compiler version, configuration and verified model hashes with this output.

--verbose 2 enables debug details, including planning. --verbose 3 also expands AIR tensor/options details. --verbose 0 keeps the Results summary without progress output.

Exit codes

0 means the module was written. The command line reference lists every code and its meaning.

Typed conversion failures include a message and may include a remediation hint. A missing golden archive raises GoldenDataNotFoundError; the CLI prints the error and path hint and exits 2. An unknown transform name is a configuration error and exits 2, as does a golden archive that cannot be read or does not match the model’s tensors (GoldenDataError) or lacks a key (GoldenDataKeyError). Check the path or setting first, and retain an unexplained traceback with the configuration and version for Support.

An existing module is not overwritten by default. For a second experiment, use a fresh output path, such as --module.path ./out-second. --force deliberately removes the previous module, including hand edits. Change configuration and regenerate instead of patching generated C.