# heliaPROFILER > Profile LiteRT and ExecuTorch models on Ambiq Apollo hardware. ## Getting started - [Getting started](https://ambiqai.github.io/helia-profiler/getting-started/index.md): Install hpx, connect your board and capture your first model profile. Learn to read the results and save a repeatable configuration. - [Install](https://ambiqai.github.io/helia-profiler/getting-started/install/index.md): Put hpx, the Arm GNU toolchain, CMake, Ninja and the SEGGER J-Link software on Linux, macOS or Windows, then confirm it with hpx doctor. - [Nix environment](https://ambiqai.github.io/helia-profiler/getting-started/nix/index.md): Reproduce the pinned hpx environment with the repository flake, choose and pin the heliaAOT release it uses, record what resolved, and know what Nix cannot provide. - [Hardware prerequisites](https://ambiqai.github.io/helia-profiler/getting-started/hardware-prerequisites/index.md): The board, probe, cable and optional power instrument a first profile needs, with the host and tool versions hpx expects, each traced to its source. - [Validate your setup](https://ambiqai.github.io/helia-profiler/getting-started/validate-your-setup/index.md): Five commands that prove the host, the probe and the board agree before you spend a build on them: doctor, boards, probes, ports and validate. - [First profile](https://ambiqai.github.io/helia-profiler/getting-started/first-profile/index.md): One command, one model, one board: run hpx profile on the bundled keyword-spotting model, then read its result bundle, clean inference timing, layer costs and memory use. - [Configure a run](https://ambiqai.github.io/helia-profiler/getting-started/configure-a-run/index.md): Move the flags from your first profile into an hpx.yml you can check in, learn how the file and the command line merge, and set the fields you will change most. - [Next steps](https://ambiqai.github.io/helia-profiler/getting-started/where-next/index.md): Pick the User guide page, the example or the reference that matches what you want to measure after your first profile. ## User guide - [User guide](https://ambiqai.github.io/helia-profiler/guide/index.md): Task pages in four groups: set up a run, measure, read results, and the concepts behind the pipeline. Start from the block you want to change. ## User guide / Set up a run - [Engines](https://ambiqai.github.io/helia-profiler/guide/engines/index.md): Choose heliaAOT for compiled inference, heliaRT for an Ambiq-tuned interpreter, or a baseline engine to compare on your board. - [Models](https://ambiqai.github.io/helia-profiler/guide/models/index.md): The model formats each engine accepts, the four keys of the model block, the tensor arena and how to size it from a measurement, and the models that ship with hpx. - [Boards and targets](https://ambiqai.github.io/helia-profiler/guide/boards/index.md): The board registry hpx profiles against, what each SoC family can capture, the CPU clock selection, probe pinning, and how to add a custom board or SoC. - [Toolchains](https://ambiqai.github.io/helia-profiler/guide/toolchains/index.md): GCC, Arm Compiler 6 and the Arm Toolchain for Embedded: which to pick, how hpx finds each one, how to install it, and how to compare them on your own model. - [Capture transports](https://ambiqai.github.io/helia-profiler/guide/transports/index.md): RTT, USB CDC, UART and SWO: what each needs plugged in, what it can lose, how hpx uses it, and when to leave the default alone. - [Memory placement](https://ambiqai.github.io/helia-profiler/guide/memory/index.md): Where the tensor arena and the model weights live, what each memory tier costs, how automatic placement decides, how to pin and tune placement, and how each engine exposes it. - [ExecuTorch NS kernels](https://ambiqai.github.io/helia-profiler/guide/executorch-ns-kernels/index.md): What the ns CMSIS-NN provider buys over arm on a Cortex-M55, measured operator by operator on an Apollo510 EVB, with the models, the verification and the reproduction recipe. - [Configuration](https://ambiqai.github.io/helia-profiler/guide/configuration/index.md): How the YAML file and the command line merge into one frozen configuration, a worked file, and the behaviour a schema table cannot express: engine notes, target overrides, build resolution and the compiler launcher. ## User guide / Measure - [PMU counters](https://ambiqai.github.io/helia-profiler/guide/pmu-counters/index.md): Which hardware counters each SoC family can capture, how to select groups and counters, how multi-pass capture and aggregation work, and how to read the per-layer results. - [Power measurement](https://ambiqai.github.io/helia-profiler/guide/power/index.md): How hpx measures current, voltage and energy around a clean inference window with a Joulescope or an on-board INA228, what each instrument gives you, and the pages that cover wiring, windows and verification. - [Joulescope setup and wiring](https://ambiqai.github.io/helia-profiler/guide/power-joulescope/index.md): Series supply wiring, the per-board GPIO pins for the gate, state and GO lines, Vref on JS220 and JS320, io_voltage, the lock-step handshake and the minimal power configuration. - [INA228 on the target](https://ambiqai.github.io/helia-profiler/guide/power-ina228/index.md): Measure whole-window energy with a TI INA228 on the board's own I2C bus: wiring a Power Monitor Click or an Adafruit breakout, choosing the shunt, the on-device summary, bring-up without a shunt, and the failure modes. - [Windows and the clean window](https://ambiqai.github.io/helia-profiler/guide/power-windows/index.md): The dedicated power firmware, how the clean window is sized and bounded, the two-clock check that verifies it, reset strategies, and the advanced power floors. - [Verifying a capture](https://ambiqai.github.io/helia-profiler/guide/power-verify/index.md): The power block of summary.json, the health signals to check before trusting a number, the window clock issue codes, bring-up diagnostics and the troubleshooting table. ## User guide / Read results - [Output files](https://ambiqai.github.io/helia-profiler/guide/output/index.md): Every file a run writes, its schema identity and version, and a field table per artifact with type, unit and the measurement boundary each number describes. - [Inference and layer timing](https://ambiqai.github.io/helia-profiler/guide/latency/index.md): What the three timing numbers in a bundle measure (the clean window, the profiled passes and the host capture), how per-layer rows relate to the total, and which configuration keys shaped each one. - [Analysis and comparison](https://ambiqai.github.io/helia-profiler/guide/analysis-comparison/index.md): Inspect a model on the host with hpx analyze, compare two result bundles with hpx compare, the comparability rules that decide which deltas are shown, and regression profiles for CI. - [Model Explorer overlays](https://ambiqai.github.io/helia-profiler/guide/model-explorer/index.md): See per-layer cost on the model graph: one overlay per counter, loaded into Model Explorer beside the model, with the node matching rules for each engine. - [Parsing outputs](https://ambiqai.github.io/helia-profiler/guide/parsing-outputs/index.md): Read a result bundle from Python and from the shell: verify the manifest, load the typed summary, pull the per-layer table into a table library, and query the JSON with jq. - [Troubleshooting](https://ambiqai.github.io/helia-profiler/guide/troubleshooting/index.md): What a failed or invalid run writes, how to read its issue codes, where each kind of failure sends you, and how to produce a redacted support bundle with hpx doctor --bundle. ## User guide / Concepts - [Concepts](https://ambiqai.github.io/helia-profiler/guide/concepts/index.md): How heliaPROFILER is built: the packages inside hpx, what each one owns, the frozen configuration and the mutable pipeline context that flow through them, and the typed error hierarchy. - [Pipeline](https://ambiqai.github.io/helia-profiler/guide/concepts/pipeline/index.md): The eighteen stages hpx profile runs in order, grouped into preflight, prepare, build, capture, power and report, with the context field each one sets and the condition under which it is skipped. - [Engine adapters](https://ambiqai.github.io/helia-profiler/guide/concepts/engine-adapters/index.md): How one engine type becomes an adapter, a typed artifact bundle and a firmware template: the registry, the four adapters, the shared CMSIS-NN and Ethos-U helpers, and the consumers that read the artifacts. - [Firmware generation](https://ambiqai.github.io/helia-profiler/guide/concepts/firmware/index.md): How hpx renders a disposable NSX application for one model and one engine: the typed render context, the template skeleton and its engine children, the project files, the generated headers, the NSX build, and the identity recorded for the image. - [Data capture](https://ambiqai.github.io/helia-profiler/guide/concepts/capture/index.md): How the host gets numbers off the board: the target lifecycle before each capture phase, the four transport backends, the line-oriented wire stream, the parser that turns it into a PmuResult, and the power capture that runs beside it. - [Field diagnostics](https://ambiqai.github.io/helia-profiler/guide/concepts/field-diagnostics/index.md): What hpx doctor --bundle collects, what it redacts and what it never reads, the versioned manifest it writes, and why the archive is byte-for-byte deterministic. - [Adding an engine](https://ambiqai.github.io/helia-profiler/guide/concepts/adding-an-engine/index.md): The touch points a fifth inference engine has to cover in hpx: the artifact type, the adapter, the registry entry, the firmware template as a child of the skeleton, template selection, the contract tests, adapter tests and the user guide page. ## Examples - [Examples](https://ambiqai.github.io/helia-profiler/examples/index.md): Runnable recipes on one fixed template, from the first profile to batch runs and saved-result analysis, each stating what it was validated on and shipping its config and, where one exists, its captured bundle. - [Profile a model](https://ambiqai.github.io/helia-profiler/examples/basic-profiling/index.md): The first real run: profile the checked-in KWS model on an Apollo510 EVB with heliaRT, read the terminal results panel, and find the five files the run wrote. - [Every counter, every layer](https://ambiqai.github.io/helia-profiler/examples/per-layer/index.md): Capture the full CPU, memory and MVE counter catalogue per layer in one run, understand the multi-pass firmware that makes it possible, and read the merged per-layer table. - [Vanilla TFLM baseline](https://ambiqai.github.io/helia-profiler/examples/tflm-baseline/index.md): Profile the upstream TensorFlow Lite Micro port with its reference or CMSIS-NN kernels to get the number every Ambiq-optimised engine is measured against. - [Compare engines on one model](https://ambiqai.github.io/helia-profiler/examples/engine-comparison/index.md): Profile the same KWS model through heliaRT, heliaAOT and the vanilla TFLM port on one board, then let hpx compare say what changed in cycles, binary size and memory, and which deltas it refuses to show. - [Compare toolchains](https://ambiqai.github.io/helia-profiler/examples/toolchain-comparison/index.md): Build the same model and engine with the GNU Arm toolchain and the Arm Toolchain for Embedded, then compare cycle counts with hpx compare; armclang follows the same recipe. - [Power capture with a Joulescope](https://ambiqai.github.io/helia-profiler/examples/power-profiling/index.md): Add a Joulescope to the bench and capture energy per inference alongside the profile: the config, the run, and the summary fields to read, with the measurement pages that explain each step. - [Atomiq110 NPU profiling (experimental)](https://ambiqai.github.io/helia-profiler/examples/atomiq110-npu-profiling/index.md): Profile a Vela-compiled model on the Ethos-U85 NPU of the experimental Atomiq110 FPGA target, capturing the Arm PMU and the NPU's own counters per layer, with heliaRT or heliaAOT. - [Interactive Python session](https://ambiqai.github.io/helia-profiler/examples/interactive-python/index.md): Drive hpx from a notebook or script with the immutable Session: load a checked-in config, branch it into heliaRT and heliaAOT experiments, resolve them without touching hardware, then profile and compare. - [Batch runs from YAML](https://ambiqai.github.io/helia-profiler/examples/batch-runs/index.md): Run a matrix of profiles without a script per case: hpx validate over the registered models, boards, engines and toolchains, or a shell loop over checked-in configs, with the run manifest as the record. - [Re-analyse saved results](https://ambiqai.github.io/helia-profiler/examples/reanalyse-results/index.md): Work with result bundles after the bench is gone: verify a bundle, load the typed summary, compare two saved runs with hpx compare, and script a regression check, all on the host. - [Per-layer cost on the model graph](https://ambiqai.github.io/helia-profiler/examples/model-explorer-overlay/index.md): Load the overlays hpx writes into Google's Model Explorer to see cycles, cache misses or vector instructions coloured onto the model's own graph. - [Read a power summary](https://ambiqai.github.io/helia-profiler/examples/power-read-summary/index.md): Take the power block of a completed capture apart: the scope it was integrated over, the energy and current figures and their units, the health signals that decide whether energy per inference may be quoted, and the jq lines that pull each out. - [Compare two power runs](https://ambiqai.github.io/helia-profiler/examples/power-compare/index.md): Hold two power captures against each other with hpx compare: the dimensions that must match for an energy delta to be shown, the issue code each mismatch reports, and how to record a baseline that stays comparable. ## Reference - [Reference](https://ambiqai.github.io/helia-profiler/reference/index.md): The contracts: every hpx command and flag, every configuration field, every issue code, the Python API, the compatibility table and baseline, and the firmware-to-host wire protocol, each generated from or checked against the source tree. - [Engine configuration](https://ambiqai.github.io/helia-profiler/reference/engine-configuration/index.md): Engine-specific settings, dependency sources and constraints for heliaRT, heliaAOT, LiteRT and ExecuTorch. - [Configuration](https://ambiqai.github.io/helia-profiler/reference/configuration/index.md): Every hpx.yml key: 106 fields across 15 configuration models, generated from the package. - [Issue codes](https://ambiqai.github.io/helia-profiler/reference/issue-codes/index.md): Every machine-readable diagnostic code hpx can emit: 27 run-validity codes and 8 comparability codes, generated from the registry. - [Compatibility baseline](https://ambiqai.github.io/helia-profiler/reference/compatibility-baseline/index.md): HPX owns the exact compatibility baseline in src/helia_profiler/data/compatibility-baseline-v1.json. It is loaded and validated during configuration resolution,… - [Compatibility table](https://ambiqai.github.io/helia-profiler/reference/compatibility/index.md): Every registered board against the four engines and three toolchains, each cell carrying the status its source states: hardware-validated from a nightly run record, experimental where the sources say so, unknown where no record exists. - [Wire protocol](https://ambiqai.github.io/helia-profiler/reference/wire-protocol/index.md): The firmware-to-host contract: every line the profiler firmware puts on a transport and the one command the host writes back, generated from the registry in helia_profiler.wire. Internal, not a user API. ## Reference / helia_profiler - [helia_profiler](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/index.md): The entry points of the heliaPROFILER Python API: one call, one session, and the progress stream they report through. - [deps](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/deps/index.md): What this build of heliaPROFILER is qualified against: the board, engine and toolchain matrix, and the locked dependency revisions a run was produced with. - [diagnostics](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/diagnostics/index.md): Collecting a redacted support bundle from a run directory, and reading one back. - [errors](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/errors/index.md): The exception hierarchy every heliaPROFILER failure is raised through, rooted at HpxError. - [evaluation](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/evaluation/index.md): Comparing two runs and judging one: the comparability rules that decide whether a comparison is meaningful, and the metric policies that turn numbers into a ve… - [examples](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/examples/index.md): Packaged model and config assets used by the examples, smoke tests and tutorials. - [modelcost](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/modelcost/index.md): The static cost model of a network, read from the model file before anything is built or run. - [runtime_records](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/runtime_records/index.md): The runtime versions this heliaPROFILER records, and whether each is qualified for a precision on a board and clock. - [vocab](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/vocab/index.md): The fixed vocabularies a configuration selects from: engines, toolchains, capture transports, memory placements and reset strategies. ## Reference / helia_profiler / config - [config](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config/index.md): The run description: what to profile, on what, how, and what to write out. - [power](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/config/power/index.md): Power capture settings: which instrument measures the rail, how it is wired to the board, and which window of the run is integrated. ## Reference / helia_profiler / power - [power](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/power/index.md): What a power capture produces: the measured result, the observations behind it, and the on-device summary the firmware reports. - [metadata](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/power/metadata/index.md): The provenance of a power number: how it was observed, what the measurement boundary included, and whether the capture holds together. ## Reference / helia_profiler / results - [results](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/results/index.md): What a profiling run produces: the run result, its per-layer and PMU detail, and the firmware and run metadata that say how it was measured. - [manifest](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/results/manifest/index.md): The on-disk index of a run directory: the artifacts it holds, the issues raised against it, and whether its numbers may be used. ## Reference / Command line - [hpx](https://ambiqai.github.io/helia-profiler/reference/cli/index.md): Profile LiteRT and ExecuTorch models on Ambiq silicon. - [hpx analyze](https://ambiqai.github.io/helia-profiler/reference/cli/analyze/index.md): Analyze model compute/parameter breakdown (no hardware needed) - [hpx boards](https://ambiqai.github.io/helia-profiler/reference/cli/boards/index.md): List supported boards and SoC capabilities - [hpx cache](https://ambiqai.github.io/helia-profiler/reference/cli/cache/index.md): Manage hpx/nsx caches - [hpx compare](https://ambiqai.github.io/helia-profiler/reference/cli/compare/index.md): Compare two hpx result directories - [hpx doctor](https://ambiqai.github.io/helia-profiler/reference/cli/doctor/index.md): Check toolchain and dependencies - [hpx engines](https://ambiqai.github.io/helia-profiler/reference/cli/engines/index.md): List available inference engines - [hpx ports](https://ambiqai.github.io/helia-profiler/reference/cli/ports/index.md): List host serial ports relevant to HPX transports - [hpx power-on](https://ambiqai.github.io/helia-profiler/reference/cli/power-on/index.md): Enable Joulescope current passthrough (keeps board powered) - [hpx probes](https://ambiqai.github.io/helia-profiler/reference/cli/probes/index.md): Inspect connected J-Link probes without opening an interactive SEGGER commander session - [hpx profile](https://ambiqai.github.io/helia-profiler/reference/cli/profile/index.md): Profile a model on target hardware - [hpx runtimes](https://ambiqai.github.io/helia-profiler/reference/cli/runtimes/index.md): Show the runtime versions this hpx records and their qualification - [hpx target](https://ambiqai.github.io/helia-profiler/reference/cli/target/index.md): Run explicit target-side utility operations - [hpx validate](https://ambiqai.github.io/helia-profiler/reference/cli/validate/index.md): Run hardware-in-the-loop validation suite (MLPerf Tiny models) ## Other pages - [heliaPROFILER](https://ambiqai.github.io/helia-profiler/index.md): Profile AI models on Ambiq hardware. Measure inference latency, inspect layer costs, and compare memory use and energy across runs.