Installation#

heliaPROFILER (hpx) needs Python plus a small set of embedded-development tools: an ARM cross-compiler, CMake/Ninja, and SEGGER J-Link software. Power capture additionally needs a Joulescope JS110/JS220/JS320 and, on Linux, a udev rule for non-root USB access.

Quick install#

curl -fsSL https://install.determinate.systems/nix | sh -s -- install

git clone https://github.com/AmbiqAI/helia-profiler.git && cd helia-profiler

nix develop
hpx doctor

nix run .#install-udev-rules

uv tool install helia-profiler

pip install helia-profiler

Requirements#

armclang and ATfE are optional alternative toolchains — see Toolchains. A Joulescope JS110/JS220/JS320 is optional and only needed for power capture — see Power Measurement. Git and initial network access to GitHub are also needed while NSX resolves and clones firmware modules. After one successful build, --offline can reuse the existing lock/module state for offline reruns.

On Windows, enable long-path support before the first build — some NSX module checkouts (e.g. ns-cmsis-nn test data) exceed the 260-character MAX_PATH limit. Both settings are required: git's, so checkouts can create the files ("Filename too long" otherwise), and the OS policy, so Python can traverse and clean them (without it, nsx sync fails with "refusing to operate on non-empty path"):

git config --global core.longpaths true

# In an elevated (Administrator) PowerShell; new processes pick it up
# immediately, no reboot needed:
Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem `
    -Name LongPathsEnabled -Value 1

1. Install heliaPROFILER#

# pip
pip install helia-profiler

# or uv (recommended for isolated tool installs)
uv tool install helia-profiler

pip install helia-profiler
# or
uv tool install helia-profiler

pip install helia-profiler
# or
uv tool install helia-profiler

Extras:

pip install 'helia-profiler[aot]'        # heliaAOT compiler support
pip install 'helia-profiler[analysis]'   # model compute/parameter analysis, no hardware needed

The AOT extra installs helia-aot>=0.19.0 and a LiteRT-compatible analysis stack. The analysis extra installs the same constrained LiteRT stack plus flatbuffer inspection support. helia-aot currently declares requires-python >=3.11,<3.13, so the aot extra needs Python 3.11 or 3.12 until that cap is lifted.

Power-measurement support (pyjoulescope_driver) ships as a core dependency — no extra install needed, just the udev rule below on Linux.

2. ARM GNU Toolchain (arm-none-eabi-gcc)#

sudo apt install gcc-arm-none-eabi

export PATH="$HOME/arm-gnu-toolchain-14.3.rel1/bin:$PATH"

export PATH="/Applications/ArmGNUToolchain/14.3.rel1/arm-none-eabi/bin:$PATH"

arm-none-eabi-gcc --version

# current session only
$env:PATH = "C:\path\to\arm-toolchain\bin;$env:PATH"

# persistently, for future terminals
[Environment]::SetEnvironmentVariable(
    "Path",
    "C:\path\to\arm-toolchain\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"),
    "User")

3. CMake and Ninja#

sudo apt install cmake ninja-build

brew install cmake ninja

winget install Kitware.CMake Ninja-build.Ninja

4. SEGGER J-Link software#

hpx drives J-Link through SEGGER Commander (JLinkExe on Linux/macOS, JLink.exe on Windows) for flashing and pylink-square (RTT/SWO capture, installed automatically with heliaPROFILER).

Discovery checks JLINK_PATH first, then both executable names on PATH, then common SEGGER install locations. Set JLINK_PATH to the full executable path for non-standard installations.

heliaPROFILER bundles a pinned, tested copy of the permissively licensed SEGGER RTT target sources. No separate RTT source checkout is required for normal use. The SEGGER J-Link host software is included in the Nix environment; uv/pip users install it separately as described above.

For testing another RTT release, hpx resolves explicit overrides in this order:

1. target.segger_rtt_path in configuration or Session.with_target()
2. The SEGGER_RTT_PATH environment variable
3. The bundled RTT target sources

An override directory must contain both RTT/SEGGER_RTT.c and Config/SEGGER_RTT_Conf.h:

git clone --branch V8.58.0 https://github.com/SEGGERMicro/RTT.git segger-rtt

Prefer explicit profile configuration over modifying PATH:

target:
    transport: rtt
    segger_rtt_path: /path/to/SEGGER_RTT

5. Joulescope (optional, for power capture)#

pyjoulescope_driver is a core dependency, so no extra pip install is needed — just make the USB device accessible:

See Power Measurement for wiring and sync-GPIO setup.

Linux USB permissions#

Installing tools in a Nix shell does not grant access to attached hardware. J-Link and Joulescope use raw USB devices; uart and usb_cdc also need access to a serial device such as /dev/ttyACM0 or /dev/ttyUSB0. Run HPX as your normal user after configuring access.

Desktop Linux#

From the repository, preview and install the rules:

nix run .#install-udev-rules -- --dry-run
nix run .#install-udev-rules

Without Nix, run bash nix/scripts/install-udev-rules.sh from the checkout. The installer uses sudo to write 70-segger-jlink.rules and 70-joulescope.rules in /etc/udev/rules.d/, reload the rules, and refresh USB devices. Unplug and reconnect the instruments afterward. The rules grant the active local desktop session access through uaccess; they do not grant every user access. Their 70- prefix places them before systemd's access handler.

NixOS#

Declare the rules in your system configuration instead of using the installer:

services.udev.packages = [
  (pkgs.writeTextDir "lib/udev/rules.d/70-hpx.rules" ''
    SUBSYSTEM=="usb", ATTR{idVendor}=="1366", MODE="0660", TAG+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"
    SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="16d0", ATTRS{idProduct}=="0e88|0e87|10ba|10b9|135a", MODE="0660", TAG+="uaccess"
  '')
];

Apply with sudo nixos-rebuild switch, then reconnect the devices. Use services.udev.packages here: NixOS writes services.udev.extraRules to 99-local.rules, after the active-session access handler.

SSH sessions and CI runners#

An SSH login or background runner may have no active local desktop session. For these hosts, give a dedicated group access to the instruments. For example, on a non-NixOS Linux host:

sudo groupadd -f hpx
sudo usermod -aG hpx "$USER"
sudo tee /etc/udev/rules.d/70-hpx-group.rules >/dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="1366", GROUP="hpx", MODE="0660", ENV{ID_MM_DEVICE_IGNORE}="1"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="16d0", ATTRS{idProduct}=="0e88|0e87|10ba|10b9|135a", GROUP="hpx", MODE="0660"
EOF
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=usb

For CI, add the account running the service to the group instead of $USER, then restart that service. For an interactive account, log out and back in. Reconnect the devices. On NixOS, declare users.groups.hpx = {};, add "hpx" to the account's extraGroups, and use GROUP="hpx" in the rules package above in place of TAG+="uaccess".

UART and USB CDC serial ports#

Check the serial device and its owning group:

hpx ports list --all
ls -l /dev/ttyACM0  # replace with the port listed by HPX

If your account cannot access that port, add it to the device's group. For example, Ubuntu/Debian commonly use dialout:

sudo usermod -aG dialout "$USER"

Use the group shown on your host, then log out and back in. On NixOS, add that group to the account's extraGroups and rebuild the system configuration. The raw-USB rules alone do not grant access to /dev/tty* devices.

Verify everything: hpx doctor#

hpx doctor
hpx probes list
hpx ports list --all

Expected output (columns will vary by platform; a dash – means an optional tool wasn't found):

Toolchain Check
╭────┬────────────────────────────────────┬────────────────────────────────╮
│    │ Tool                               │ Path                           │
├────┼────────────────────────────────────┼────────────────────────────────┤
│ ✓  │ ARM GCC toolchain                  │ /usr/bin/arm-none-eabi-gcc     │
│ ✓  │ CMake (>= 3.24)                    │ /usr/bin/cmake                 │
│ ✓  │ Ninja build system                 │ /usr/bin/ninja                 │
│ ✓  │ SEGGER J-Link commander            │ /usr/bin/JLinkExe              │
│ ✓  │ neuralspotx Python package         │ installed                      │
│ ✓  │ pylink Python package (RTT/SWO     │ installed                      │
│    │ transport)                         │                                │
│ –  │ heliaAOT compiler                  │ not installed                  │
│ –  │ ARM Compiler (armclang)            │ not installed                  │
│ –  │ ARM fromelf (armclang)             │ not installed                  │
╰────┴────────────────────────────────────┴────────────────────────────────╯

All required tools found.

✓ means the dependency was found; – rows are optional (only needed for heliaAOT or an alternative toolchain). hpx doctor does not replace checking that your installed compiler, CMake, and J-Link versions meet the table above. Once every required row shows ✓, continue to First Profile.