First Profile#

A guided, no-config first run: from unboxing an Apollo EVB to a per-layer cycle-count table in about five commands.

Before you start#

• Installed heliaPROFILER and the toolchain — hpx doctor shows all required tools as ✓.
• An Ambiq Apollo EVB, powered and connected to your host over its J-Link USB connector (the on-board debug USB port — check your specific EVB's quick-start card if it has more than one USB connector).

You also need a LiteRT .tflite model. Replace /path/to/model.tflite below with your model path. If you installed with pip into the active Python environment, heliaPROFILER includes a small deterministic example model:

python -c "from helia_profiler.examples import tiny_cnn; print(tiny_cnn())"

Use the printed path in the commands below. A source checkout also contains examples/quickstart/kws_model.tflite. uv tool install keeps packages in an isolated environment, so supply your own model or use the source-checkout path.

1. Confirm the toolchain#

hpx doctor

All required rows should show ✓ (see Installation if not).

2. Find your J-Link probe#

hpx probes list

serial      product                    connection
----------  -------------------------  ----------
801000001  J-Link-OB-Apollo4-CortexM  USB

If nothing is listed, check the USB cable and that the SEGGER J-Link software from Installation is installed.

3. Find your board name#

heliaPROFILER needs a --board value that matches your EVB. List every board it knows about:

hpx boards

Match the silkscreen/part number on your EVB against the Board column (for example apollo510_evb for an Apollo510 EVB). The default board is apollo510_evb — pass --board <name> explicitly if yours is different.

4. Run the profiler#

hpx profile /path/to/model.tflite --board apollo510_evb

With no other flags, heliaPROFILER:

Progress prints stage-by-stage. The first run takes longer because NSX resolves and clones the pinned heliaRT and firmware modules, then configures, builds, flashes, and captures. Subsequent runs are faster because module and build artifacts are cached.

5. Look at the result#

Four files matter on your first run:

results/
├── result_manifest.json ← bundle validity, provenance, and artifact digests
├── summary.json         ← headline metrics; read this first
├── profile_results.csv  ← per-layer breakdown for spreadsheets
└── run_metadata.json    ← resolved config and environment provenance

Open summary.json:

{
  "engine": "helia-rt",
  "layers": 13,
  "total_cycles": 123456.0,
  "overflow_detected": false,
  "top_layers": [
    {"index": 1, "op": "CONV_2D", "cycles": 34567},
    {"index": 4, "op": "DEPTHWISE_CONV_2D", "cycles": 23456}
  ],
  "memory": { "arena_size": 131072, "allocated_arena": 29780 }
}

Three things to read off:

• total_cycles — the headline cost of one inference, averaged across iterations.
• top_layers — which ops dominate runtime. Optimization effort goes here.
• memory.allocated_arena — how much RAM TFLM actually used. If it's much smaller than arena_size, you can shrink the arena.

Before consuming the headline metrics, check validity and issues in summary.json or result_manifest.json. A result is valid, degraded, or invalid; structured issues explain any capture or integrity problem.

6. View the per-layer table#

profile_results.csv has one row per layer, one column per counter. See Output & Reports for the full column reference and what each counter means. The same data is also rendered as Model Explorer overlays under results/model_explorer/.

7. Keep going#

Now that you've got a baseline:

• Repeatable runs? → Quick Start with a config file
• Different model placement? → Memory Placement
• Try heliaAOT? → Inference Engines
• Faster build with armclang? → Toolchains
• Add power numbers? → Power Measurement

Troubleshooting the first run#