ppk2-mcp

A headless driver, command line and MCP server for the Nordic Power Profiler Kit II, wrapped around the device layer of Nordic's own nRF Connect Power Profiler app.

Why it wraps the official app instead of reimplementing it

The PPK2's accuracy does not live in its command set, which is a handful of opcodes. It lives in the per-unit calibration the instrument reports at connect time and in the conversion that turns a 14-bit ADC reading, a measurement range and that calibration into a current - including the filter that suppresses the spike a range switch produces. Those are the parts that change when Nordic ships new instrument firmware, and they are the parts a reimplementation gets wrong quietly: the numbers still look like currents.

So vendor/pc-nrfconnect-ppk is a submodule of the app itself, and src/device/serialDevice.ts inside it is imported and used as-is. Nothing in this repository converts an ADC reading. Tracking a new firmware release is a submodule bump.

What this repository adds is the part the app cannot give a script: the app is an Electron program with a chart, and what a measurement needs is a number attributed to a state.

What it measures that an average does not

The instrument samples current and eight digital channels together at 100 kSa/s. Wire a digital channel to a pin the firmware drives to mark a state - a radio powered down, a peripheral clocked, a task running - and the capture can say what that state cost, rather than what the board averaged while it was happening.

That is the whole design. Captures are stored as RUNS: maximal spans over which the digital word did not change, each with its sample count, mean, extremes and charge. A run file is three orders of magnitude smaller than the samples behind it, loses nothing any per-state question needs, and is small enough to commit beside the result it supports.

Two things are deliberately not smoothed over:

• A sample the instrument's own payload counter says was lost is counted as lost and does not close a run. A dropout is not a state change, and it is not a current either. A capture that lost more than the caller allows is REFUSED rather than averaged, because loss is not spread evenly across the states.
• A state is the MASKED digital word, so channels nothing is clipped to cannot split a run in two. probe reports every channel so the mask can be chosen from what is actually wired.

Install

Node 20 or newer, and a PPK2 on USB.

git clone --recurse-submodules https://github.com/schuschu/ppk2-mcp
cd ppk2-mcp
npm install

If node is not on PATH, export PPK2_NODE_BIN=/path/to/node/bin and the ./ppk2 launcher will find it.

On Linux the user needs read and write on the instrument's serial port, which usually means membership of dialout.

Command line

./ppk2 list
./ppk2 info
./ppk2 probe --seconds 5
./ppk2 capture --out /tmp/run --seconds 60 --mask 0x0f \
    --names txrx,addr,txen,rxen --label "what this run is"

probe says which digital channels are wired. capture writes <out>.runs.csv and <out>.meta.json and prints one line per digital state. It exits nonzero when the instrument lost more than --max-dropped-ppm of the stream.

MCP server

./node_modules/.bin/tsx src/mcp.ts

or as a stdio server entry:

{
  "command": "npm",
  "args": ["--prefix", "/path/to/ppk2-mcp", "run", "--silent", "mcp"]
}

Tools: ppk2_list, ppk2_info, ppk2_probe, ppk2_capture, ppk2_analyze.

Every tool answers with aggregates and file paths. None of them returns samples: at 100 kSa/s a minute of capture is six million of them, which is neither a reply a caller can hold nor one a reader can check. ppk2_analyze reads a run file back, and given a digital state and a set of duration edges it splits that state's runs by how long they lasted - which is how two states one pin cannot distinguish are told apart by the length of the interval instead.

The instrument is opened per call and closed after it, because one process at a time can hold the port and a server that kept it would lock out both the app and the command line.

Modes

Nothing here ever enables a source output. The instrument is used in whatever mode it is already in, and the harness this was written for is an ammeter in series with a board powered by its own supply - on a Nordic DK, the current measurement header with its jumper removed.

Licence

The vendored app and this wrapper are under Nordic's licence; see vendor/pc-nrfconnect-ppk/LICENSE.