# ppk2-mcp

MCP server for Nordic Semiconductor's [Power Profiler Kit II](https://www.nordicsemi.com/Products/Development-hardware/Power-Profiler-Kit-2) (PPK2). Provides 12 tools for discovering, connecting, configuring, and measuring current draw directly from Claude Code or Claude Desktop.

## Features

- **Discover** PPK2 devices on USB
- **Connect** with automatic calibration loading
- **Configure** source/ampere mode and supply voltage
- **Measure** current at ~100 kHz native sample rate
- **Log** raw measurements to timestamped CSV files
- **Inspect** saved logs without leaving the conversation

## Requirements

- Python 3.10+
- Nordic Semiconductor PPK2 hardware
- USB connection to PPK2

## Quick Start

```bash
git clone https://github.com/Ultrahuman-tech/ppk2-mcp.git
cd ppk2-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Then configure your MCP client (see below).

## Configuration

### Claude Code

Add to `~/.claude.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "ppk2": {
      "command": "/path/to/ppk2-mcp/.venv/bin/python3",
      "args": ["/path/to/ppk2-mcp/ppk2_server.py"],
      "type": "stdio"
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ppk2": {
      "command": "/path/to/ppk2-mcp/.venv/bin/python3",
      "args": ["/path/to/ppk2-mcp/ppk2_server.py"]
    }
  }
}
```

Replace `/path/to/ppk2-mcp` with the actual clone location.

## Tools Reference

| Tool | Description |
|------|-------------|
| `list_devices` | Scan USB for connected PPK2 devices |
| `connect` | Connect to a PPK2 and load calibration (returns session ID) |
| `disconnect` | Disconnect, stop measurement, power off DUT |
| `set_mode` | Set operating mode: `source` (PPK2 powers DUT) or `ampere` (external power) |
| `set_voltage` | Set supply voltage in mV (source mode only, 800-5000 mV) |
| `power_control` | Toggle DUT power on/off |
| `get_session_info` | Show current session state |
| `start_measuring` | Begin continuous current measurement |
| `stop_measuring` | Stop continuous measurement |
| `measure` | Atomic: start, collect for N seconds, stop, save CSV, return stats |
| `list_logs` | List saved measurement CSV files |
| `get_log` | Read a saved log file (metadata + first N rows) |

## Typical Workflow

```
list_devices          → find PPK2 on USB
connect               → get session_id
set_mode "source"     → PPK2 supplies power
set_voltage 3300      → 3.3V to DUT
power_control "on"    → power up the device
measure 5.0           → capture 5 seconds of current data
disconnect            → clean up
```

## Logs

Raw measurement data is saved to the `logs/` directory as timestamped CSV files. Each file contains:

- Comment header with metadata (date, duration, mode, voltage, sample count, sample rate)
- CSV data columns: `sample_idx`, `current_ua` (optionally `digital` for digital channels)

Example:
```
# PPK2 Raw Measurement Log
# Date: 2025-02-18 19:57:00
# Duration: 2.01s
# Mode: source
# Voltage: 3300 mV
# Samples: 200,544
# Sample Rate: 99,773 sps
sample_idx,current_ua
0,1523.45
1,1518.22
...
```

## Known Issues

- **Stale serial buffer on reconnect**: After a previous session crashes or is interrupted, the PPK2's serial buffer may contain leftover binary measurement data. The server handles this automatically by flushing the buffer before reading calibration data.
- **Metadata decode errors**: The upstream `ppk2-api` library can crash on binary noise in the serial buffer. This server includes a built-in patch (latin-1 fallback) so no manual library edits are needed.

## License

MIT - see [LICENSE](LICENSE).