# Getting started

heliaPROFILER (`hpx`) builds profiling firmware, runs your model on an Ambiq
board and saves the measurements. Start here to capture your first result,
understand its timing and memory use, and save a configuration for the next run.

You need a supported host, an Ambiq board and a J-Link connection. Power
measurement is optional and requires a supported instrument.

## Your first profile

Follow these steps in order, or jump to setup validation if your tools are already installed.

- [1. Install](https://ambiqai.github.io/helia-profiler/getting-started/install/): Put hpx, the Arm GNU toolchain, CMake, Ninja and the SEGGER J-Link software on your machine, with one path per operating system.
- [2. Hardware prerequisites](https://ambiqai.github.io/helia-profiler/getting-started/hardware-prerequisites/): What to plug in: the board, its debug USB port, the probe hpx will use, and the instruments you need only for power.
- [3. Validate your setup](https://ambiqai.github.io/helia-profiler/getting-started/validate-your-setup/): Check the tools and connection before running a hardware smoke test: doctor, boards, probes, ports and validate.
- [4. First profile](https://ambiqai.github.io/helia-profiler/getting-started/first-profile/): One command, one model, one board. Then the result bundle, clean timing, layer costs and memory use.
- [5. Configure a run](https://ambiqai.github.io/helia-profiler/getting-started/configure-a-run/): Move the flags into a YAML file you can check in, and learn how the file and the command line merge.
- [6. Next steps](https://ambiqai.github.io/helia-profiler/getting-started/where-next/): Pick the User guide page, the example or the reference that matches what you want to measure.

## What a run does

Every `hpx profile` invocation is the same sequence of blocks. The diagram
below is the shape to keep in mind while you read the rest of the section;
the [Concepts pages](https://ambiqai.github.io/helia-profiler/guide/concepts/) open each block up.

One profile, six blocks: Configure, analyse, build, flash, capture, report. Power capture is an optional block beside capture.

1. Configure: YAML and flags
2. Analyse: model and memory
3. Build: firmware
4. Flash: J-Link
5. Capture: PMU, power
6. Report: result bundle
Text description of the diagram

- Configure: YAML and flags
- Analyse: model and memory
- Build: firmware
- Flash: J-Link
- Capture: PMU, power
- Report: result bundle

## Expected output

At the end of step 4 you have a `results/` directory holding
`result_manifest.json`, `summary.json`, `profile_results.csv`,
`run_metadata.json` and `nsx.lock`, and a per-layer table you can open in a spreadsheet.
Step 5 leaves you with an `hpx.yml` that reproduces that run from one
command.

## What next

Start with [Install](https://ambiqai.github.io/helia-profiler/getting-started/install/). If your tools are already in place, jump to
[Validate your setup](https://ambiqai.github.io/helia-profiler/getting-started/validate-your-setup/) and let `hpx doctor` tell you
whether that is true.