Configuration#

heliaPROFILER uses a layered configuration system: a YAML file merged with CLI flags, resolved once at startup into an immutable config object.

For the complete key-by-key schema, see the Configuration Reference. Calling heliaPROFILER from Python directly? See the Python API configuration reference for ProfileConfig and its section classes.

Config file#

Create an hpx.yml (any name works — pass it with --config):

model:
  path: my_model.tflite       # (1)!
  arena_size: 131072           # (2)!

engine:
  type: helia-rt               # (3)!
  config:                      # (4)!
    variant: release-with-logs

target:
  board: apollo510_evb         # (5)!
  toolchain: arm-none-eabi-gcc # (6)!
  jlink_serial: ""             # (7)!

profiling:
  pmu_counters:                # (8)!
    cpu: all
    memory: all
    mve: all
  per_layer: true              # (9)!
  iterations: 5                # (10)!
  warmup: 2

power:
  enabled: false               # (11)!
  driver: joulescope
  mode: external
  duration_s: 30
  io_voltage: 1.8

output:
  format: csv                  # (12)!
  dir: ./results
  model_explorer: true         # (13)!
  detailed: false              # (14)!

1. Path to the .tflite model file.
2. Optional tensor arena override in bytes. Start with the default, then tune from the reported allocated_arena. heliaAOT uses its own memory plan.
3. Engine: tflm, helia-rt, helia-aot, or executorch.
4. Engine-specific config (passed through to the adapter).
5. Target board — run hpx boards to see options.
6. Toolchain selection. GCC and armclang are discovered on PATH; ATfE is resolved through ATFE_ROOT.
7. Optional — select a specific J-Link probe by serial number.
8. PMU counter groups and selections. See PMU Counters.
9. Per-layer breakdown (vs. whole-model aggregate).
10. Inference iterations per PMU pass (averaged in results).
11. Enable Joulescope power capture. See Power Measurement.
12. Output format: csv or json.
13. Generate Model Explorer overlay JSONs. See Model Explorer.
14. Emit detailed per-preset CSVs and memory breakdown (--detailed).

CLI overrides#

CLI flags override YAML values. Anything you can set in YAML can also be specified on the command line:

hpx profile --config hpx.yml \
    --board apollo3p_evb \
    --iterations 50 \
    --engine helia-aot \
    --output-dir ./my_results

The model path can also be a positional argument:

hpx profile my_model.tflite --board apollo510_evb

Config resolution order#

1. Load YAML config file (if --config provided)
2. Override with CLI flags
3. Apply defaults for any unset fields
4. Freeze into an immutable ProfileConfig dataclass

After this point, the config is never mutated. Every stage reads from the same frozen object.

Field notes#

The complete key-by-key schema (types, defaults, deprecations) lives in the generated Configuration Reference. The notes below cover behavior that a schema table can't express.

heliaRT config notes#

• engine.config.resolver_ops now defaults to auto for helia-rt. Leave it unset unless you specifically want the broader all resolver surface.
• With no engine path override, HPX resolves the pinned nsx-helia-rt module through the NSX registry. Use source_path, dist_path, or source only for an explicit local/custom runtime.
• target.clock.cpu is the supported way to choose CPU frequency. Set it to one of the board's named speeds (lp/hp, or ulp/lp/hp on Atomiq); HPX validates the selection against the chosen board's platform registry entry and maps it onto the correct NSX perf mode in the generated firmware. Leave it unset to use the board's lowest-power tier.
• Models with CALL_ONCE, VAR_HANDLE, ASSIGN_VARIABLE, or READ_VARIABLE do not need special-case firmware patches in config; HPX now enables the resource-variable runtime automatically when model analysis sees those ops.
• If a helia-rt run succeeds, use the reported allocated_arena to tighten model.arena_size instead of growing the arena blindly.

Advanced target overrides#

• target.custom_boards adds config-scoped board definitions without editing the built-in platform registry.
• target.custom_socs adds config-scoped SoC definitions for bring-up cases where the built-in SoC metadata is not sufficient.
• target.custom_boards.<name>.based_on clones an existing built-in board and lets you override fields like channel, psram_kb, and default_sync_gpio_pin.
• target.custom_boards.<name>.starter_profile_board reuses the NSX starter profile from a built-in board when the custom board should inherit its module graph.
• target.custom_boards.<name>.ble_reset_gpio_pin is the GPIO wired to an onboard Cooper BLE controller's reset line on a "Blue" board, held low during power captures. Inherited from based_on; leave it unset (or write null) on boards with no onboard radio. Unlike its three sibling pin keys, 0 does not mean "disabled" here and is rejected as ambiguous — see Boards → Adding a new board.
• The four target.custom_boards.<name>.*_gpio_pin keys take a plain integer pad number. Booleans are rejected rather than resolving to pads 1 and 0: these pins are driven for the duration of a power capture, so a typo'd true would silently put an unrelated GPIO inside your measurement.
• target.custom_socs.<name>.app_flash_load_addr declares the first flash address above the part's bootloader-reserved region. It is inherited from based_on when you name one; with neither — or with an explicit null, which overrides inheritance — HPX treats the address as unknown and refuses the fallback flash rather than guessing from family. This changed: an entry with no based_on previously inherited its family's address. See Boards → App flash load address for the upgrade note.
• Unrecognized keys in target.custom_socs and target.custom_boards are rejected with the list of supported keys, a close-match suggestion where one applies, and no silent discarding. Both blocks accept a free-form description:.

Build-resolution notes#

• By default, generated profiler apps keep the board's normal NSX channel, but HPX pins the verified peeled commits for neuralspotx-v0.7.17 (8b5a7fa9…b44f) and nsx-ambiq-sdk v5.2.24 (a9f4ec25…1132) in the qualified compatibility baseline.
• build.nsx_modules.<module>.ref or .version overrides win over that default for the owning project.
• build.nsx_modules.<module>.path installs a local module checkout into the generated app and bypasses registry resolution for that module only.
• Ordinary profiles reuse a compatible nsx.lock byte-for-byte and run nsx sync --frozen; they do not check or advance upstream refs. A lock is resolved only when missing or structurally incompatible.
• Set build.update_dependencies: true (CLI: --update-dependencies) for the explicit operation that refreshes refs and rewrites the lock. It cannot be combined with offline mode.
• Set build.offline: true (CLI: --offline) to require both a compatible lock and already-materialized exact module trees. The legacy --frozen flag is retained as an alias for this strict mode.
• Cached applications are isolated by a deterministic workspace fingerprint covering the compatibility baseline and registry hashes, target/toolchain, engine backend/variant/version, overrides (including local content hashes), and module-relevant build settings.

Compiler-launcher notes#

• auto (the default) wraps every compile with sccache or ccache if either is found on PATH, and does nothing otherwise — so simply installing the binary opts you in. Caching is correctness-safe (the launcher hashes the full compile inputs) and only accelerates the compile step, not NSX lock/sync/configure or flash.
• none (also off/false) disables the launcher.
• An explicit tool name or path (e.g. sccache) is required: the build fails if it cannot be found.
• The HPX_COMPILER_LAUNCHER environment variable overrides this field, and the --compiler-launcher / --no-compiler-launcher CLI flags override both.

Validation#

• Unknown keys anywhere in the config tree are rejected at load time, with did-you-mean suggestions based on the real field names.
• Every config error raised is a ConfigError carrying a hint describing how to fix it.