ScopeMCP — DS1102 Oscilloscope MCP Server

<p align="center"> <img src="resources/images/ScopeMCP_klein.png" alt="ScopeMCP Logo" width="200"> </p>

A Python MCP server that connects the Owon/Abestop DS1102 (Firmware V3.1.0) oscilloscope (Firmware V3.1.0) to AI assistants like Claude via the Model Context Protocol.

Available Tools

Status & Metadata

• get_connection_status: Checks connection, model, run status, and timestamp.
• get_live_metadata: Returns full device metadata (timebase, sample rate, channel/trigger config).
• get_measurements: Provides frequency, period, scale, probe factor, and coupling for both channels.

Waveform Capture

• capture_waveform(channel, max_samples): Captures a single channel (fixed at 1520 hardware samples, software downsampled).
• capture_dual_waveform(max_samples): Efficiently captures both channels in a single operation.

Voltage conversion formula:

voltage = (raw - OFFSET) / 250.0 * scale_v * probe_factor

Note: The DS1102 always transfers 1520 samples over USB. Downsampling occurs in software.

Vertical & Horizontal Control

• set_vertical_scale(channel, scale): e.g., "1V", "500mV".
• set_channel_coupling(channel, coupling): AC, DC, or GND.
• set_voltage_offset(channel, offset): Vertical position in Volts.
• set_horizontal_scale(scale): e.g., "1ms", "500us".

Trigger & Device Control

• set_trigger_mode(mode): AUTO, NORMAL, SINGLE.
• set_trigger_source(source): CH1, CH2.
• set_trigger_slope(slope): RISE, FALL.
• set_trigger_level(level_mv): Threshold in millivolts (e.g., 500.0 for 0.5V).
• set_run_state(state): RUN or STOP.
• run_autoset(): Performs automatic oscilloscope setup.

Requirements

• Python 3.10+
• libusb backend (on Windows: install via Zadig)
• DS1102 connected via USB

pip install mcp libusb-package pyusb

Setup

Detailed installation instructions can be found in doc/INSTALL.md.

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ds1102-scope": {
      "command": "python",
      "args": ["C:/path/to/ds1102_mcp.py"]
    }
  }
}

Live Monitor (Grabber)

In addition to the MCP server, this repository includes ds1102_grabber.py. This is a lightweight live oscilloscope frontend (GUI) that allows for a real-time view of both channels directly on your PC.

Features

• Dual-Channel Live View: Simultaneous display of CH1 and CH2.
• Real-Time Synchronization: Automatically adjusts scaling (V/div) and probe factor (1X/10X) when changed on the device.
• Clean Grid Mode: The grid in the grabber perfectly matches the divisions on the hardware oscilloscope (no confusing numerical labels).
• Keyboard Shortcuts: Basic control directly via keyboard (e.g., SPACE for RUN/STOP).

Running the Grabber

Ensure the oscilloscope is connected via USB and dependencies (matplotlib, numpy, pyusb) are installed.

python ds1102_grabber.py

---

Known Limitations

• Capture speed (~7–10s): The DS1102 always transfers the full 1520-sample buffer over USB. The :DATA:WAVE:POINTS SCPI command has no effect on transfer size for this firmware. This is a confirmed hardware limitation — see FINDINGS_USB_Transfer_Limit.md.
• run_status never shows STOP: The firmware always reports TRIG in the status field, even when stopped. This is a firmware behavior, not a server bug.
• CH2 returns zeros when DISPLAY: OFF: No signal data is available from a channel that is disabled on the scope.

Protocol Notes (Firmware V3.1.0)

• Every SCPI command is prefixed with a 4-byte little-endian length header.
• Commands must end with \n (0x0A).
• Screen data: 1520 samples × 2 bytes signed 16-bit little-endian = 3040 bytes + 4-byte header.
• Full protocol details: see doc/ds1102_protocol.md.

License

GNU GPLv3