ppk2lab

English · 繁體中文 · 简体中文 · 日本語

See exactly where your device's power goes. ppk2lab turns the Nordic Power Profiler Kit II into a scriptable measurement lab: record current and eight digital signals on one timeline, decode low-speed UART and SPI, and attribute energy to individual protocol events. Everything is reachable from Python, the command line, or an AI agent, so a power regression can fail a CI build the same way a failing test does.

Highlights

ppk2lab lets humans and agents:

• discover and configure one or more PPK2 devices;
• capture calibrated current and all D0-D7 digital states on one synchronized timeline;
• decode low-speed UART and SPI traffic (9,600 baud and 10 kHz SCLK are the top rate tier);
• measure charge, energy, peak current, latency, and the distribution (p50/p90/p99) of a window or a decoded event, with a typical per-range error bar;
• work with hour-scale captures: read a manifest without its samples, read one window, or export a decimated summary;
• trigger captures from current, digital state, UART content, or SPI transactions;
• run reproducible power assertions in local automation and CI;
• watch a live device in a browser: ppk2lab web serves a console with the current trace, D0-D7 on the same timeline, and — only with --allow-control — the controls that change device state;
• say when the samples cannot support an answer — dropped samples, ADC saturation, a window with no data in it — instead of returning a confident number;
• try everything without hardware via --simulate.

Install

The core package requires Python 3.11 or newer. pyserial is the only runtime dependency. The browser console needs a server, and that server is opt-in: pip install 'ppk2lab[web]'.

pipx install ppk2lab        # recommended for the CLI
# or inside a virtual environment:
pip install ppk2lab

ppk2lab --version
ppk2lab doctor --json

# optional: the browser console
pip install 'ppk2lab[web]'
ppk2lab --simulate web      # http://127.0.0.1:8765/, no hardware needed

0.5.1 is the current release and 0.2.0 was the first stable one, so a plain pip install ppk2lab resolves it. It is labelled experimental on purpose: the toolchain is heavily tested without hardware, and the properties that keep a measurement honest are enforced rather than assumed — but the hardware validation behind it is partial. One unit, macOS only, and no decoder has yet read a real signal. Roadmap says exactly what that covers and what it does not; read it before you trust a number.

Run from a development checkout:

git clone https://github.com/tipoLi5890/ppk2lab
cd ppk2lab
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ppk2lab doctor --json

Claude Code plugin

After installing the ppk2lab CLI, add this repository as a Claude Code marketplace and install its skills:

/plugin marketplace add tipoLi5890/ppk2lab
/plugin install ppk2lab@ppk2lab

During plugin development, load the checkout directly with claude --plugin-dir ./.

Codex plugin and loose skills

The skills in skills/ are plain SKILL.md files that Codex can load directly; a Codex plugin manifest is not published yet, so use the loose-skill path below.

For repository-scoped loose skills, place them in .agents/skills/. For a user-wide installation:

mkdir -p ~/.agents/skills
cp -R skills/* ~/.agents/skills/

Claude Code can use the same skill sources from .claude/skills/ or through the bundled plugin. Full setup and troubleshooting lives in INSTALL.md.

Quickstart

Every command also runs without hardware by adding --simulate, which uses a built-in simulated PPK2 to exercise the toolchain. A simulated run is not a measurement.

Inspect the environment and connected devices without changing hardware state:

ppk2lab doctor --json
ppk2lab discover --json
ppk2lab info --device <serial> --json

Capture current and D0-D7. capture never enables DUT power:

ppk2lab capture --device <serial> --duration 5s --digital D0-D7 --output capture.ppk2a

See what the artifact actually holds — timeline, gaps, warnings, calibration — without loading a sample:

ppk2lab inspect capture.ppk2a --json

Decode a supported low-speed UART signal and measure energy by frame:

ppk2lab decode capture.ppk2a --uart D0 --baud 9600 --output uart.jsonl
ppk2lab measure capture.ppk2a --annotations uart.jsonl --group-by frame --json

Run a reproducible power assertion:

ppk2lab assert capture.ppk2a \
  --rule 'p99_current < 15mA' \
  --rule 'after uart("TX_DONE"), within 20ms, avg_current < 10uA' \
  --format json

For a CI threshold, prefer a percentile to max_current: range switches accumulate as a capture runs longer, so a maximum drifts upward with capture length while p99_current does not.

These commands are implemented today. Every JSON contract carries schema_version 1 and has followed the stability policy in docs/SPEC.md since 0.2.0: additions are backward compatible, and a removal or a change of meaning needs a schema_version bump and a migration note.

What it does

Scope and physical limits

PPK2 samples its digital inputs at 100 kS/s. Protocol decoding is therefore intended for low-speed signals. Tier boundaries are samples per bit at that fixed rate — 10, 5, and 2.5 — and nothing else. The top tier covers:

• UART up to 9,600 baud;
• SPI clock up to 10 kHz;
• all eight digital inputs D0-D7;
• higher rates only when explicitly marked conditional or experimental.

This project is not intended to replace a MHz-class logic analyzer. A frame that crosses a missing-sample interval is reported as incomplete or invalid, never as a confident decode.

Every capture reports the samples it lost. Most of the loss 0.2.0 measured turned out to be self-inflicted: the artifact writer compressed each 4 MB chunk on the thread feeding samples in, and the ~290 ms pause overflowed the reader's queue. That is why those 60-second captures each lost exactly five whole chunks — one per chunk boundary crossed. Compression now runs on its own thread and the reader's queue is bounded in bytes rather than in reads, and on the same host six consecutive captures (5 × 30 s and 1 × 60 s) recorded every sample: no gaps, complete: true. What the host itself costs under load is now unquantified — it was never separated from the writer's own stalls — so treat loss as possible, reported, and no longer expected.

Hardware safety

• configure is a dry run unless --apply is given.
• capture never enables DUT power and has no option that would — and neither does an earlier configure --dut-power on --apply, because the PPK2 de-energizes VOUT once the host closes the serial port. Measured on one unit: still live at 0 ms of closure, a coin flip at 100-250 ms, off every time from 500 ms on. Powering a DUT through the meter therefore has to happen inside the same open session that captures (ppk2lab.PPK2 in Python); configure --dut-power on --apply warns W_DUT_POWER_TRANSIENT rather than implying otherwise.
• Source voltage is expressed as voltage_mv, checked against device capabilities, and never inferred from a DUT name.
• Mode changes, DUT power, source voltage, and reset operations report the previous and resulting state.
• On completion or failure, the library attempts to restore the session's starting power state and records whether restoration succeeded.
• No plugin hook or skill may automatically enable DUT power, change voltage, or reset a device.
• ppk2lab web is a viewer unless --allow-control is given, binds 127.0.0.1, and refuses --allow-control on any other address. It can never reset the device, set a user gain, choose which device to open, or raise the session's voltage ceiling. Because the server holds the port for its whole lifetime, closing the browser tab does not de-energise VOUT — only stopping the server does.

Use with AI agents

Every operation is available as a typed Python API and as a CLI command with stable JSON output. Read-only inspection is separated from operations that change hardware state.

Command surface:

ppk2lab discover
ppk2lab info
ppk2lab capabilities
ppk2lab schema
ppk2lab configure
ppk2lab capture
ppk2lab inspect
ppk2lab decode
ppk2lab measure
ppk2lab assert
ppk2lab compare
ppk2lab export
ppk2lab doctor

Commands that enable DUT power, change source voltage, or reset hardware are explicitly identified as state-changing. Voltage arguments include their unit in the API name, such as voltage_mv.

An optional agent adapter may be provided as a separate package. The core driver and file formats do not depend on one agent framework.

Every JSON result carries a schema version, stable error code, remediation hint, completion state, and sample-gap information. ppk2lab capabilities --json describes the live command and decoder surface, and publishes the coded warning, gap-reason, and interruption-reason catalogs, so an agent does not need to infer unsupported behavior or parse prose to learn what a W_* code means.

Bundled agent skills

The plugin ships two skills built on progressive disclosure instead of one oversized prompt: each SKILL.md is a thin router that keeps the safety contract inline and maps tasks to per-topic reference notes the agent reads only when needed. Live knowledge — commands, options, decoder rate tiers, schemas, error codes — is never duplicated into prompts; agents query the self-describing CLI (capabilities --json, schema, doctor --json) instead.

Skills provide workflow guidance; the ppk2lab CLI remains the deterministic execution and validation layer. Installation never enables DUT power or starts a capture automatically.

Architecture

USB CDC transport
  -> device discovery and capability query
  -> streaming frame assembler
  -> raw sample parser and sequence-gap detector
  -> calibration and synchronized D0-D7 transitions
  -> trigger engine
  -> UART/SPI decoder plugins
  -> event-level charge and energy analysis
  -> capture files, CSV, VCD, JSONL, Python, and CLI

The canonical capture format preserves raw samples, calibration metadata, device and firmware identity, capture configuration, timestamps, and data-loss markers. Processed exports never replace the original evidence.

Official references

PPK2 functionality is based on Nordic Semiconductor's official PPK2 documentation and the official Power Profiler app repository. These official materials define the product behavior and compatibility reference for this project.

The project does not distribute Nordic firmware binaries. Firmware installation and updates should be performed with Nordic's official tools unless separate redistribution permission is established.

Nordic Semiconductor, Power Profiler Kit, and PPK2 may be trademarks or product names of Nordic Semiconductor ASA. Their use here is solely to identify compatible hardware.

See docs/sources.md and docs/protocol-spec.md for the Nordic official references and documented PPK2 behavior used by the project.

Roadmap

0.5.0 is released. What is still open is validation rather than implementation, and it is worth knowing which is which. One hardware session on 2026-08-20 ran the tool end to end on a single unit — firmware fingerprint HW=49625 IA=59.0 keys=40 ports=2, macOS on Apple silicon — covering discovery, metadata, calibrated capture at 100 kS/s, interruption recovery, and every offline command. These are not validated, and each needs hardware that session did not have:

• a physical pass on Windows and on Linux, where the OS reports the USB interface numbers macOS does not;
• a second unit and a second firmware fingerprint, only one of each having been seen;
• a cross-check that can resolve gain error: a resistor an order of magnitude tighter than ±5%, or a calibrated reference;
• UART and SPI decoder validation on real signals from an MCU fixture, against defined error-rate thresholds;
• hot-unplug recovery, an 8-24 h soak run, and a multi-device session — plus a bandwidth sweep and a load that crosses a current-range boundary;
• Claude Code and Codex skill installation verified against the current releases, and the documentation and examples reproduced from a clean environment.

The browser console 0.4.0 shipped without a server has one in 0.5.0: pip install 'ppk2lab[web]' and ppk2lab web. It has not been run against a physical PPK2 either — every test behind it uses the simulator, which exercises the protocol and the state machine but not the instrument. docs/webui.md says what it does, what it refuses to do, and what has not been proven.

The decoder support tiers are named for the rate each was designed against, not for a measured error rate — nothing has been measured yet. Validation that needs hardware has no CI workflow and is not meant to, so the maintainer runs it on the bench and fills in the compatibility matrix as units and platforms are covered. See ROADMAP.md for that matrix and for what is deliberately not being built.

Documentation

Contact

Questions, bugs, compatibility reports, and feature requests should be filed through GitHub Issues.

License

Released under the MIT License. It covers the original material in this repository only — PPK2 hardware, Nordic firmware, Nordic documentation, and trademarks remain with their owners.

Development

This project is developed with assistance from Claude Code and OpenAI Codex.