# 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`.