# devpsu

Agent-friendly bench power supply control, built for the Agentic Firmware
Workbench. Set voltage/current, switch the output, and power-cycle the device
under test on B&K Precision 1685B/1687B/1688B supplies (and Manson HCS-3xxx,
which share the same protocol) — from the command line or from an AI agent
via MCP.

Sibling of [devpower](https://github.com/JacobBeningo/devpower) (USB port
power) and devsignal (signal generation). Typical use: an agent's DUT wedges
hard enough that a debug-probe reset doesn't help — the agent runs
`power_cycle` on the supply and the board cold-boots.

## Supported hardware

Built against the **1687B** (36 V / 10 A). The ASCII-over-serial protocol is
shared by the 1685B (60 V / 5 A) and 1688B (18 V / 20 A) and the Manson
HCS-3xxx family they're based on. USB appears as a virtual COM port
(9600 8N1) — no drivers needed on macOS/Linux.

Note for the 1685B: it uses two current decimals; pass
`--current-decimals 2` (CLI) or `current_decimals=2` (API).

## Install

```bash
pip install .
```

Requires Python 3.10+.

## Safety model

An agent controlling DUT power deserves guardrails. devpsu has four:

1. **Session limits (human-in-the-loop)** — on the first supply-changing
   MCP call of a session, the *user* is prompted (MCP elicitation) for the
   session's max voltage/current. Agent requests above them require
   explicit user approval; `output_on`/`power_cycle` check the present
   setpoints too, and `output_off` is never gated. Hosts without
   elicitation support fail safe (over-limit requests are refused).
2. **Environment hard ceiling** — set `DEVPSU_MAX_V` / `DEVPSU_MAX_A` and
   any request above them is refused before touching the hardware — not
   even in-session user approval overrides these.
3. **The supply's own protection** — `devpsu limits --ovp 5.5 --ocp 1.0`
   programs the instrument's OVP/OCP as a second, firmware-level layer.
4. **Agent-facing guidance** — the MCP tool descriptions tell agents to
   verify setpoints against the DUT's rating before enabling the output.

Also set `DEVPSU_PORT` to pin the serial port on single-supply benches:
auto-discovery probes USB-serial ports with a benign query, which you may
not want on a bench with DUT consoles attached.

## Multiple supplies

`devpsu list` shows every supply with its USB **location**, model maxima,
and present setpoints. Identical supplies often ship USB bridges with the
same serial number, making `/dev/cu.usbserial-*` names unstable - so
`--port` (and the MCP `port` argument) also accepts the location string,
which is tied to the physical USB topology:

```bash
$ devpsu list
/dev/cu.usbserial-0001  loc=34-2.1.4.1.2.1  max 36.2V/12.0A  set 24.0V/2.0A
/dev/cu.usbserial-4     loc=34-2.1.4.1.4    max 36.2V/12.0A  set 12.1V/3.0A
$ devpsu --port 34-2.1.4.1.4 status     # select by location
```

Session safety limits are kept **per physical supply** (keyed by
location), so each rail gets its own ceiling and its own approval
prompts.

## CLI

```bash
devpsu list                        # probe for supplies
devpsu status                      # setpoints, live V/A, CV/CC, limits
devpsu set --volts 3.3 --amps 0.5
devpsu on / devpsu off
devpsu cycle --hold 5              # power-cycle the DUT
devpsu limits --ovp 5.5 --ocp 1.0
devpsu raw GETD                    # protocol escape hatch
devpsu --json status               # machine-readable
```

## MCP server

`devpsu-mcp` runs an MCP server over stdio exposing `list_supplies`,
`get_status`, `set_voltage`, `set_current`, `output_on`, `output_off`,
`power_cycle`, and `set_protection`.

Register with Claude Code (with guardrails):

```bash
claude mcp add --scope user devpsu -e DEVPSU_MAX_V=5.5 -e DEVPSU_MAX_A=2 devpsu-mcp
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

The test suite runs against a fake serial layer — no supply required.

## License

MIT