# PPK2 reference runner

**Reference script outline — not tested with a physical PPK2 here.** Uses the open-source, unofficial `ppk2-api` Python package. It captures current and the PPK2 logic channel, integrates complete GPIO-high windows, and divides window charge by a declared number of decisions. It does not build firmware, flash a board, calibrate the instrument or certify a measurement receipt.

## Prepare the rig

Use an nRF54LM20 DK, a PPK2 and an SDK-built application with a known card and firmware hash. Confirm the DK's actual revision, CPU clock, supply topology and measurement rail against Nordic documentation. Isolate the DUT rail so USB/debugger power does not bypass the instrument. Connect common ground, the selected GPIO marker to the PPK2 logic input, and the required safe logic reference. Do not change wiring while powered. Never attach two supply sources to the same DUT rail.

The default **ampere mode** requires a separately powered DUT; the runner does not switch DUT power. Source mode is optional and must be selected explicitly after confirming safe wiring and voltage. The calibration/supply setting is not a measurement of the actual rail. Close the official Power Profiler application before opening its serial port. The PPK2 data port is not the DK UART port.

## Install and capture

```sh
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install ppk2-api
python3 measure.py --port /dev/ttyACM1 --seconds 10 \
  --marker-channel 0 --calls-per-window 10000 \
  --sample-rate-hz 100000 --voltage-v 3.0 --voltage-evidence assumed \
  --output capture-001
```

Port, duration and calls above are reference settings, not published protocol values. Confirm the actual PPK2 rate; `--sample-rate-hz` reconstructs timestamps and does NOT configure the hardware. The inspected API streams at a nominal 100 kS/s. The published FICUS campaign used about 1 kS/s exported captures; this outline does not reproduce that campaign. Verify the installed package's API/version and lock it for your experiment. API calls were checked against upstream source on 6 November 2026, not exercised on hardware.

## Firmware marker contract

Raise the GPIO immediately before a batch of calls and lower it after the final class is published. Use the same fixed ordered feature vectors and actual `calls-per-window` for every compared engine. Preserve class outputs in an observable sink so optimization cannot remove the calls. Replay validation probes first. Keep initialization/warmup, reset policy, IRQ policy and rounds in the experiment manifest. Reverse engine order in a subsequent round to check ordering sensitivity.

C1 means **processed float features already in RAM → published class**, CPU only. Acquisition, raw waveform windowing, DSP, radios, UART and verbose logs are outside this boundary. The marker and loop add overhead: quantify them with a matched control or disclose them. Until those checks exist, call this an instrumented decision-window result, not a clean reproduction of the published C1 result. Individual short calls can fit between current samples; batch enough work to resolve a stable interval. The script rejects windows with fewer than ten samples and discards incomplete opening/closing intervals.

## Calculation and output

`get_samples(raw)` returns `(current_ua, logic_bits)` lists; `digital_channels(bits)` provides eight logic streams. The runner uses rectangular integration: `Q[nC] = sum(I[µA]) × dt[µs] / 1000`. It reports gross charge per decision. Supply an independently measured matched `--idle-ua` only to obtain a separately named idle-corrected result; do not treat low-marker time, sleep or zero current as a baseline by default.

For a constant rail, `E[nJ] = Q[nC] × V[V]`. Default energy is derived at **assumed 3.0 V**, not absolute measured energy. `--voltage-evidence measured --voltage-record rail.json` records the hash of your independently obtained constant-voltage evidence; the script does not verify that file. A varying rail requires time-aligned integration of `V(t) × I(t)`, not this conversion.

Output is `raw.bin`, `samples.csv` and `summary.json`. CSV timestamps use the reconstructed device sample clock, never the host's read timing. This API exposes no device timestamps or sequence counters; lost bytes, buffering, instrument filtering and dropped samples can corrupt the result without detection. Validate capture continuity with independent synchronization markers and compare reconstructed duration with expected firmware intervals. Raw hashes bind captured bytes, not firmware authenticity. Add card, firmware, workload, SDK/flags, board, rail, pin mapping, sample rate, repetitions, baseline and edge-sensitivity records before publishing evidence. Do not infer confidence intervals or peak SRAM from these files.

## Source and licensing

Upstream API source: https://github.com/IRNAS/ppk2-api-python/blob/master/src/ppk2_api/ppk2_api.py . Package: https://pypi.org/project/ppk2-api/ . `ppk2-api` is GPL-2.0; review dependency licensing before distributing it in a product. This independently written outline does not imply IRNAS or Nordic endorsement. Public FICUS evidence remains bound to its frozen campaign, not to any new capture produced by this script.
