# devsignal

Agent-friendly signal generator control for the embedded bench, built for the
Agentic Firmware Workbench. Configure waveforms and switch outputs on Siglent
SDG-series generators — from the command line or from an AI agent via MCP.

Sibling of [devpower](https://github.com/JacobBeningo/devpower) (USB power
control). Typical use: an agent testing an ADC driver or input-capture
firmware needs a known stimulus — it sets a 1 kHz sine at 2 Vpp, enables the
output, runs the test, and switches the output off.

## Supported hardware

Built and verified against the **SDG2042X**; the `C{n}:BSWV` / `C{n}:OUTP`
SCPI dialect is shared across the Siglent SDG family (SDG1000X/2000X/6000X),
so other models are expected to work.

Transport is PyVISA with the pure-Python `pyvisa-py` backend:

- **USB** (USBTMC): plug in and go — needs `libusb` (`brew install libusb` /
  distro package).
- **LAN**: pass `--resource "TCPIP::<ip>::INSTR"` — no drivers needed.

## Install

```bash
pip install .
```

Requires Python 3.10+.

## CLI

```bash
devsignal list                                  # find instruments (USB)
devsignal idn                                   # identity
devsignal status                                # both channels: wave + output
devsignal wave 1 sine --freq 1000 --amp 3.3     # configure CH1
devsignal wave 1 square --freq 1e6 --amp 3.3 --duty 25
devsignal output 1 on --load HZ                 # enable CH1 into Hi-Z
devsignal output 1 off
devsignal raw "C1:BSWV?"                        # raw SCPI escape hatch
devsignal --json status                         # machine-readable
```

## MCP server

`devsignal-mcp` runs an MCP server over stdio exposing `list_instruments`,
`get_status`, `set_wave`, `set_output`, and `scpi` (raw escape hatch), with
agent-facing safety guidance baked into the tool descriptions.

Register with Claude Code:

```bash
claude mcp add --scope user devsignal devsignal-mcp
```

## Safety notes

- **Load setting scales the delivered voltage.** A 50 Ω setting driving a
  high-impedance input delivers *twice* the programmed amplitude. Use
  `--load HZ` when driving MCU/logic inputs.
- **Session limits (human-in-the-loop):** on the first amplitude-affecting
  MCP call of a session, the *user* is prompted (MCP elicitation) for the
  session's max amplitude; agent requests above it require explicit user
  approval, and raw `scpi` amplitude changes are gated the same way. Hosts
  without elicitation support fail safe (over-limit requests are refused).
- **Hard ceiling:** set `DEVSIGNAL_MAX_VPP` (e.g. `3.3`) in the MCP server's
  environment and nothing above it is accepted - not even with in-session
  user approval.
- Configure the waveform first, verify with `status`, then enable the output.

## Development

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

The test suite runs against a fake VISA layer — no instrument required.

## License

MIT