Capture Transports#

heliaPROFILER supports four ways to get profiling data off the target. The transport affects reliability, throughput, and what hardware you need plugged in. RTT is the default and is recommended.

How transport selection works#

hpx profile model.tflite --transport rtt       # default
hpx profile model.tflite --transport usb_cdc
hpx profile model.tflite --transport uart
hpx profile model.tflite --transport swo

or in YAML:

target:
  transport: rtt

The choice is global across the run — every PMU pass and metadata block flows over the same transport. uart uses the J-Link OB virtual COM port at 115200 8N1, so it is the low-throughput fallback when USB CDC is unavailable. HPX does not automatically retry with another transport after failure because the transport changes both generated firmware and capture reliability.

RTT (recommended)#

Segger Real-Time Transfer uses dedicated buffers in target RAM that the host reads over SWD. No target peripherals are involved during transfer, which keeps PMU data clean.

Hardware#

• J-Link probe connected via SWD to the target.
• The same USB connection used for flashing — no extra cables.
• SEGGER RTT target sources bundled with heliaPROFILER. Use target.segger_rtt_path or SEGGER_RTT_PATH only to test an explicit alternate checkout.

How heliaPROFILER uses it#

• Opens an RTT session through pylink after JLinkExe resets the target.
• Uses a 32 KB up-buffer in the firmware (configured via NSX in trim mode). Lines are scanned for the HPX protocol sentinels.
• Supports the PSRAM model handshake: firmware emits HPX_PSRAM_READY, the host writes the model directly to PSRAM via J-Link, and the firmware proceeds with HPX_GO.

Pros / cons#

USB CDC#

The target enumerates as a USB CDC ACM serial device (TinyUSB). The host opens that serial port and reads the same HPX protocol stream.

Hardware#

• USB cable from the EVB's target USB connector (not the J-Link USB) to the host.
• A J-Link is still required for flashing and target reset.
• Both cables stay plugged in throughout the run.

How heliaPROFILER uses it#

• Auto-detects the target serial port by VID/PID.
• Reads through pyserial, line-buffered.
• The firmware pauses USB polling (Timer 3) around each PMU measurement window so USB interrupts don't pollute the counters.

Pros / cons#

SWO (legacy / diagnostic)#

Serial Wire Output streams data over the SWO pin via the target's ITM stimulus port 0. Captured via the J-Link probe using the pylink API.

Hardware#

• J-Link probe with the SWO pin connected. Most Ambiq EVBs route SWO through the J-Link header by default.

Caveats#

Choosing a transport#

graph TD
    A[Start] --> B{Is RTT working?}
    B -->|Yes| C[rtt — default]
    B -->|No| D{Need lossless?}
    D -->|No| E[swo]
    D -->|Yes| F{Target USB CDC available?}
    F -->|Yes| G[usb_cdc]
    F -->|No| H[uart]

For 95% of runs, the default rtt is correct. Switch to usb_cdc when:

• You're capturing extremely large per-layer data (every counter, every iteration, every layer) and the 32 KB RTT buffer is filling.
• Your host has flaky pylink/J-Link RTT support but the target USB works fine.
• Your board does not expose a usable target USB CDC path, but the J-Link OB virtual COM port is available — use uart as the fallback.

Troubleshooting#