Skip to main content
Glama
msox2014a-mcp
by SMEAC
README.md
# msox2014a-mcp

An MCP server that lets AI assistants drive an **Agilent/Keysight MSO-X 2014A** mixed-signal
oscilloscope (InfiniiVision 2000 X-Series) over USB or LAN with SCPI/VISA. It also works with a
DSO-X 2014A, including one upgraded to MSO by licence. It also includes a **built-in simulator**,
so you can use it without the hardware.

Its tool layout follows [sandraschi/oscilloscope-mcp](https://github.com/sandraschi/oscilloscope-mcp).
It adds features specific to this bench scope: 8 digital channels, the built-in WaveGen,
the scope's own measurement engine, screenshots, saving and recalling setups, and raw SCPI.

<p align="center">
  <img src="docs/images/ch1_square_1kHz.png" width="48%" alt="1 kHz square wave captured after autoscale">
  <img src="docs/images/ch1_rise_time.png" width="48%" alt="Rise-time measurement with threshold markers">
</p>
<p align="center"><em>Screenshots taken through the server from a real scope:
the 1 kHz probe-compensation signal after autoscale (left) and its rising edge at 200 ns/div,
measured at 970 ns (right).</em></p>

## Features

| Area | What you get |
|---|---|
| Connection | VISA discovery (USBTMC / VXI-11 / HiSLIP), auto-detection of the 2014A, simulator (`SIM`) |
| Configuration | Per-channel V/div, offset, coupling, probe ratio, BW limit, invert, label; timebase; acquire mode (normal / average / high-res / peak) |
| Trigger | Edge trigger on CH1-4, D0-D7, EXT, LINE, WGEN; slope, sweep, coupling, holdoff, HF/noise reject; arm, force, status |
| Capture | `:DIGitize` single-shot or fetch-without-reacquire; 8- or 16-bit transfer; normal or raw (full 100 kpt) record; digital pod |
| Analysis | Host-side Vpp/Vmax/Vmin/Vtop/Vbase/amplitude/mean/RMS/frequency/period/duty/widths/rise/fall/overshoot; phase and delay; FFT with peaks, harmonics and THD |
| Scope-side | The instrument's own `:MEASure` engine (Vpp, frequency, duty, rise time, phase, delay, …) |
| Output | Decimated preview arrays (min/max, peak-preserving), CSV export, JSON summary, PNG screenshot |
| WaveGen | Sine, square, ramp, pulse, noise, DC, with frequency, amplitude, offset, duty, symmetry and width |
| Licences | Reads `*OPT?` and gives a clear error for unlicensed features (WaveGen, MSO) instead of a VISA timeout |
| Escape hatch | `scope_scpi` for any SCPI command, including binary block queries |

## Install

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). The project pins uv to a
**uv-managed** interpreter (`python-preference = "only-managed"`). The Microsoft Store Python
runs sandboxed and cannot load vendor VISA DLLs; it fails with `VI_ERROR_LIBRARY_NFOUND` even
when Keysight IO Libraries is installed correctly.

```powershell
git clone https://github.com/SMEAC/mcp_msox2014a.git
cd mcp_msox2014a
uv sync
uv run msox2014a-mcp --simulate   # quick smoke run (stdio; Ctrl+C to exit)
```

### VISA backend for real hardware

| Option | Setup | Notes |
|---|---|---|
| **Keysight IO Libraries Suite** (recommended on Windows) | Install it. Leave `MSOX_VISA_LIBRARY` unset. | Provides the USBTMC driver. Connection Expert shows the resource string. |
| NI-VISA | Install it. Leave `MSOX_VISA_LIBRARY` unset. | |
| pyvisa-py (pure Python) | `MSOX_VISA_LIBRARY=@py` | LAN works out of the box. USB needs libusb and a WinUSB driver bound to the scope through Zadig, which replaces the vendor driver. |

Connect the scope with the **rear USB device port** (type B). LAN requires the DSOXLAN module.

The USB resource looks like `USB0::0x0957::0x1798::MY56271763::0::INSTR`: vendor 0x0957, product
0x1798 for this scope family, then the serial number and the USB interface number. Use the exact
string that `scope_device(operation='list')` or Keysight Connection Expert reports.

### Troubleshooting the first connection

| Symptom | Cause and fix |
|---|---|
| `VI_ERROR_LIBRARY_NFOUND` with Keysight IO Libraries installed | The venv was built on the Microsoft Store Python. Delete `.venv` and run `uv sync`; the project pins a uv-managed Python. Restart Windows once after installing IO Libraries. |
| `list` finds no USB instrument with `@py` | pyvisa-py can't open a device bound to the Windows USBTMC driver. Use Keysight IO Libraries, or bind WinUSB with Zadig. |
| `*IDN?` reports `DSO-X 2014A` | Normal for a DSO upgraded to MSO by licence: the model string doesn't change. `scope_device(operation='options')` should list `MSO`. |
| A command times out instead of returning an error | The scope never answers queries for an unlicensed subsystem. The server checks `*OPT?` for WaveGen and MSO; for others, check `options`. |
| Banner on the scope screen ("Data out of range", "Hardware missing") | A command the scope rejected. `scope_device(operation='errors')` shows it; the banner clears after a few seconds. |

## Register with an MCP client

**Claude Code**

```powershell
claude mcp add msox2014a -- uv run --directory C:\dev\mcp_msox2014a msox2014a-mcp
# simulator only:
claude mcp add msox2014a-sim -- uv run --directory C:\dev\mcp_msox2014a msox2014a-mcp --simulate
```

**Claude Desktop / Cursor / VS Code** (`mcp.json` / `claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "msox2014a": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\dev\\mcp_msox2014a", "msox2014a-mcp"],
      "env": {
        "MSOX_RESOURCE": "USB0::0x0957::0x1798::MY12345678::0::INSTR",
        "MSOX_MCP_CAPTURE_DIR": "C:\\scope_captures"
      }
    }
  }
}
```

Replace the resource string with your scope's. Run `scope_device(operation='list')` to find it.
For Claude Code, put the same block in a project-level `.mcp.json`. That file is machine-specific
(local path, scope serial), so it's git-ignored; `.mcp.json.example` is a starting point.
HTTP transport is also available: `msox2014a-mcp --transport http --port 10940`.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `MSOX_RESOURCE` | *(unset)* | VISA resource to auto-connect on first tool call. `SIM` selects the simulator. |
| `MSOX_VISA_LIBRARY` | *(unset → vendor VISA, falling back to `@py`)* | `@ivi`, `@py`, or a path to a VISA DLL |
| `MSOX_MCP_CAPTURE_DIR` | `~/msox2014a_captures` | Where CSV, JSON, PNG and setup files are written |
| `MSOX_LOG_LEVEL` | `WARNING` | Log level. Logs go to stderr. |

CLI flags: `--transport {stdio,http,sse}`, `--host`, `--port`, `--resource`, `--simulate`, `--log-level`.

## Tools

Each tool takes an `operation` argument, the same pattern as the reference server.

| Tool | Operations |
|---|---|
| `scope_device` | `list`, `connect`, `disconnect`, `status`, `identify`, `options`, `reset`, `clear`, `autoscale`, `errors` |
| `scope_configure` | `channel`, `timebase`, `acquire`, `digital`, `get`, `save_setup`, `recall_setup` |
| `scope_trigger` | `set`, `get`, `force`, `arm`, `status` |
| `scope_capture` | `single`, `fetch`, `preview`, `export_csv`, `export_summary`, `last`, `screenshot`, `run`, `stop` |
| `scope_measure` | `all`, `fresh`, `scope`, `fft`, `phase`, `list` |
| `scope_wavegen` | `get`, `set`, `on`, `off` |
| `scope_scpi` | raw command, mode `auto` / `write` / `query` / `binary` |
| `scope_help` | `quickstart`, `tool_help`, `hardware_guide`, `faq`, `discover` |

Resources: `msox://status` and `msox://capture/last`.
Prompts: `characterize_signal` and `wavegen_loopback`.

Any errors waiting in the scope's error queue (`:SYSTem:ERRor?`) are added to tool results
under `scope_errors`.

### Example session

```text
scope_device(operation="connect")                         # auto-detect
scope_device(operation="autoscale")
scope_capture(operation="single", channels="1,2", points=10000)
scope_measure(operation="all")
scope_measure(operation="phase", channel=1, channel2=2)
scope_measure(operation="fft", channel=1)
scope_capture(operation="screenshot")
scope_capture(operation="export_csv", file_name="run1")
```

`single` uses `:DIGitize`, which leaves the scope **stopped**. Call
`scope_capture(operation="run")` to go back to a live display.

## Simulator

`resource="SIM"` (or `--simulate`) starts an in-process fake MSO-X 2014A. It accepts the same
SCPI as the real scope, in long or short form, so the real driver code runs against it unchanged.
The simulated bench wiring is:

- **CH1**: the WaveGen output when WaveGen is on, otherwise a 1 kHz, 2 Vpp sine
- **CH2**: a 1 kHz, 0–3.3 V square wave at 30 % duty, lagging CH1 by 90°
- **CH3**: a 5 kHz, 1 Vpp triangle wave
- **CH4**: unconnected (noise only)
- **D0–D7**: an 8-bit counter clocked at 8 kHz

The simulator models trigger alignment, the trigger timeout in NORMAL sweep, noise that scales
with V/div and drops with averaging, autoscale, 8- and 16-bit transfers, setup save and recall,
and PNG screenshots.

## Project layout

```text
src/msox2014a_mcp/
  server.py     FastMCP tools, resources, prompts
  driver.py     MSOX2014A SCPI driver (channels, timebase, trigger, capture, WaveGen, ...)
  transport.py  PyVISA transport and discovery
  simulator.py  SCPI-speaking simulator (implements the same Transport protocol)
  analysis.py   numpy measurements, phase, FFT/THD, min/max decimation
  scpi.py       mnemonic canonicalisation, source naming, response parsing
  session.py    connection state, capture directory
  help_text.py  content for scope_help
tests/          driver + MCP end-to-end tests (run against the simulator)
```

## Development

```powershell
uv run pytest
```

## Status and limitations

- **Verified on hardware:** a DSO-X 2014A upgraded to MSO (firmware 02.65), over USB with Keysight
  IO Libraries 2026. Checked: discovery, identify and options, autoscale, channel and timebase
  setup, edge trigger, single capture of analog and digital channels, scope-side and host-side
  measurements (they agree), and screenshots. The WaveGen commands could only be tested on the
  simulator, because this scope has no WaveGen licence. Serial decode, mask testing and the setup
  file round-trip haven't been tried on hardware yet. If the real scope rejects anything,
  `scope_device(operation='errors')` shows what it complained about.
- Only the edge trigger is wrapped. For glitch, pattern, TV and serial triggers, use `scope_scpi`.
- Serial protocol decoding (`:SBUS`, a licensed option) is not wrapped. For UART, SPI and I²C,
  capture the digital channels and decode them on the host, or use `scope_scpi`.
- The scope's math and FFT functions (`:FUNCtion`) are not wrapped. FFT runs on the host in
  `scope_measure(operation='fft')`. It needs several cycles in the record to judge harmonics
  (it warns when there are too few).
- Measurements shown on the scope display (`:MEASure:<item> <source>`, with markers) aren't
  wrapped yet; use `scope_scpi`. `:MEASure:STATistics` doesn't exist on the 2000 X-Series.

## License

MIT - see [LICENSE](LICENSE).

TDQS

B3.4/5.0

Scored across 8 tools

Disambiguation4/5

Each tool maps to a distinct stage of scope work (connect, configure, trigger, capture, measure, wavegen), so an agent can generally pick correctly. The main soft spots are scope_measure vs scope_capture (both produce signal data) and scope_scpi, which can theoretically do anything the other tools do.

Naming Consistency5/5

All eight tools use a uniform scope_<noun/verb> snake_case pattern with no deviations. The prefix also correctly identifies the server's instrument domain.

Tool Count5/5

Eight tools is well within the sweet spot and each covers a coherent functional area: session, configuration, trigger, acquisition, measurement, wavegen, raw SCPI, help. No tool feels redundant or padded.

Completeness4/5

The core lifecycle — discover/connect, configure, trigger, capture, measure, generate — is fully covered, plus a raw SCPI escape hatch and help. Secondary areas like math/FFT setup, cursors, serial decode, or save/recall of instrument setups are absent, though SCPI can bridge them.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues