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.

[!IMPORTANT] This project is experimental and is not affiliated with or endorsed by Nordic Semiconductor ASA.

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;
• detect dropped samples instead of silently compressing time;
• decode low-speed UART and SPI traffic (9,600 baud / 10 kHz validated);
• measure charge, energy, peak current, and latency for each decoded event;
• trigger captures from current, digital state, UART content, or SPI transactions;
• run reproducible power assertions in local automation and CI;
• try everything without hardware via --simulate.

Install

The core package requires Python 3.11 or newer. The final runtime dependency set will be frozen before the first PyPI release.

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

ppk2lab --version
ppk2lab doctor --json

The package is not on PyPI yet. Until the 0.1.0 release, install it from a source checkout as shown below; the current version is 0.1.0.dev0.

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

Open the Codex plugin browser with /plugins, add the repository marketplace, and install ppk2lab. Exact non-interactive commands will be verified against the current Codex release before publishing.

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 without automatically enabling DUT power:

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

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 'after uart("TX_DONE"), within 20ms, avg_current < 10uA' \
  --format json

These commands are implemented today. Every JSON contract carries schema_version 1 and remains subject to change until the 0.1.0 release.

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. The initial validated targets are:

• 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.

Hardware safety

• configure is a dry run unless the user explicitly applies the change.
• Capture does not enable DUT power unless a user-approved profile or explicit option requests it.
• 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.

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 decode
ppk2lab measure
ppk2lab assert
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 so an agent does not need to infer unsupported behavior.

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

The following work remains open before the first release:

• a hardware compatibility matrix covering Windows, macOS, and Linux across firmware versions, multiple devices, and hot unplug;
• a calibration cross-check against the official Power Profiler app using known loads;
• UART and SPI decoder validation on real signals against defined error-rate thresholds;
• long-duration soak tests for streaming, memory use, and recovery;
• release gates: a frozen public API baseline, a dependency license audit, a release rehearsal, and the PyPI publish itself.

See ROADMAP.md for versioned exit criteria and the hardware compatibility matrix.

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.