Skip to main content
Glama
RIGOL Lab MCP

RIGOL Lab MCP

by WindSweeps

RIGOL Lab MCP

让 AI 通过结构化工具连接实验仪器的 Python / MCP 框架。优先支持 USB,预留 LAN; 射频源、函数/任意波形发生器和示波器共用设备管理、参数模型和通信层。

当前为框架版本,真实仪器仅支持发现、连接和身份查询。具体型号驱动尚未加入。 完整的设置、输出和测量流程已在模拟设备中实现。模拟值不代表实测结果。 本项目与 RIGOL 无隶属关系。

支持范围

功能

当前状态

MCP stdio 服务、类型化工具、设备能力查询

已实现

USB VISA 资源发现、连接、读取 *IDN?

已实现;尚未经过实机验证

LAN TCPIP INSTR / SOCKET 入口

已实现,显式配置启用;尚未经过实机验证

真实型号的输出、采集和测量命令

等待具体型号及固件信息

模拟射频源、信号发生器、示波器

已实现

同一设备串行操作、超时、连接清理、可选操作日志

已实现

有长度限制的 IEEE 488.2 二进制块读取

已实现,供后续驱动使用

Related MCP server: rigol-oscilloscope-mcp

安装

需要 Python 3.11+。在 Windows PowerShell 中:

git clone https://github.com/WindSweeps/rigol-lab-mcp.git
cd rigol-lab-mcp
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe examples/demo.py

Linux/macOS 将 Python 路径替换为 .venv/bin/python。

项目使用官方 MCP Python SDK 的 1.x API,并将依赖限制为 <2,避免自动升级到不兼容 的主版本。PyVISA 是 Python 接口;实际 USB 通信还需要可用的 VISA 后端和设备驱动。

接入 AI 客户端

DeepSeek Harness(DSH)

在项目目录中激活已经安装本项目的虚拟环境,再让 DSH 加载 配置文件:

source .venv/bin/activate
dsh --profile headless --patch "$PWD/examples/dsh.patch.yml" "调用 rigol-lab 的 list_instruments"

PowerShell 使用 .\.venv\Scripts\Activate.ps1 激活,再运行 同一条 dsh --profile headless 命令。 从桌面应用启动时,把示例中的 insert 条目加入对应 profile 的 cordis.patch.yml,并将 command 改为虚拟环境中 rigol-lab-mcp 可执行文件的绝对路径。 接入实物设备时,将 args 改为 ['--config', '/absolute/path/config.local.json']。 启动后可调用 list_instruments 检查服务状态。

通用 MCP stdio

在支持本地 MCP stdio 的客户端中添加以下配置,替换为你的实际绝对路径:

{
  "mcpServers": {
    "rigol-lab": {
      "command": "C:/path/to/rigol-lab-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "rigol_lab_mcp", "--mode", "sim"]
    }
  }
}

这是通用 MCP 配置示例;客户端的配置文件位置和外层格式可能不同。 服务默认进入模拟模式。标准输出专供 MCP 协议使用,日志写入标准错误或配置的文件。 直接在终端启动服务时,它会等待客户端的协议输入,这是正常行为。

建议向 AI 发出:

列出模拟仪器,连接 SIM::AWG 和 SIM::SCOPE。将信号发生器 CH1 设置为 1 kHz、1 Vpp、零偏置正弦波,打开输出。采集 1000 点并读取频率、峰峰值和 RMS。明确标注模拟结果,完成后关闭信号源输出。

模拟接线为 SIM::AWG CH1 → SIM::SCOPE CH1,理想单位增益。模拟器支持正弦、 方波和三角波。测量值是完整周期的解析计算;采样波形按时基生成。 探头、耦合、触发、削顶、带宽和 RF 传播未建模,示波器相应设置仅保留为元数据。 射频模拟器独立于该接线,不模拟通过示波器测量 RF 的过程。

USB 接入

  1. 安装适合设备的 VISA 运行时/驱动,通过 RIGOL Ultra Sigma 验证连接。

  2. 使用仪器 USB DEVICE 口连接电脑。前面板 USB HOST 口通常用于外部存储。

  3. 复制 examples/usb.example.json 为 config.local.json。

  4. 以 VISA 模式启动并调用 list_instruments,取得实际 USB VISA 地址。

  5. 将该地址加入本地 allowed_resources 列表,重启服务后调用 connect_instrument。

Copy-Item examples/usb.example.json config.local.json
.\.venv\Scripts\python.exe -m rigol_lab_mcp --config C:/path/to/config.local.json

AI 客户端也使用上面 --config 参数替换 --mode sim。配置路径建议使用绝对路径。 未列入 allowed_resources 的设备可以被发现,但不能连接。 读取/写入结束符和超时在本地配置中指定,应按具体手册核实。 连接过程仅发送身份查询,不发送复位、清错或输出命令。 未匹配型号驱动时,get_capabilities 返回 identity_only,控制操作明确报错。

后续 LAN

复制 examples/lan.example.json 并填写实际 VISA 资源地址。示例 IP 192.0.2.10 是文档保留地址,不能直接连接。enable_lan 默认关闭。

可使用设备支持的 TCPIP INSTR 资源或 TCPIP SOCKET 资源;协议、设备名、端口和结束符 必须根据具体仪器手册确定。不要假定所有型号都使用相同端口。 LAN 采用显式地址配置,不扫描网段;无需修改 AI 工具或型号适配器。

若选择纯 Python 的 @py 后端:

.\.venv\Scripts\python.exe -m pip install -e ".[lan]"

示例中 @py 面向 LAN。USB 使用该后端还涉及 PyUSB/libusb 和系统驱动,不在此框架中 自动安装或更换。不要为了这个项目自动替换已经能工作的厂商 USB 驱动。 同一服务中已连接的设备会按厂商、型号和非空序列号去重;切换 USB/LAN 前先断开。 外部程序/其他进程的并发访问不受本进程锁保护,应由实验台统一安排访问。

工具接口

工具

参数

含义

list_instruments

无

发现资源及列出已连接会话

set_connection_inventory

inventory

接收中台插件提交的设备连接清单

connect_instrument

resource

打开连接并返回 instrument_id

disconnect_instrument

instrument_id

关闭通信,不修改输出状态

get_capabilities

instrument_id

身份、支持操作、限值、模拟标记

get_state

instrument_id

可读取的当前状态

configure_waveform_generator

instrument_id, settings

波形、Hz、Vpp、偏置 V、相位、负载

configure_rf_source

instrument_id, settings

频率 Hz、功率 dBm

configure_scope

instrument_id, settings

V/div、s/div、探头倍率、耦合、触发

set_output

instrument_id, settings

通道及显式输出开关

acquire_waveform

instrument_id, settings

通道及点数,上限 10000

measure

instrument_id, settings

通道及 frequency_hz/vpp/rms_v/mean_v

工具的 JSON Schema 由 Python/Pydantic 类型自动生成。NaN、无穷值、非法枚举、未知字段 和超界点数会被拒绝;型号之间不同的限值由适配器继续校验。 模拟设备仅支持 CH1。配置工具不会隐式打开输出。

设备中台插件接口

中台或主 agent 通过 MCP 调用 set_connection_inventory,提交完整清单:

{
  "inventory": {
    "schema_version": 1,
    "devices": [
      {"resource": "TCPIP0::192.0.2.10::inst0::INSTR", "label": "实验台示波器"}
    ]
  }
}

resource 是可传给 connect_instrument 的 VISA 资源字符串,label 是可选的显示名称。 成功时返回 {"schema_version":1,"received":1}。每次提交完整替换旧清单, 空数组清除清单。重复地址或不符合 schema 的提交返回 MCP 工具错误,并保留上一份清单。

主 agent 从 list_instruments 的 connection_inventory 读取中台上报的清单, 从 connected 读取本服务已打开的会话。两方应使用同一个 MCP 服务进程。 清单保存在进程内,服务重启后由中台重新提交。提交清单不打开连接或授予访问权限。 实际连接仍由 connect_instrument 发起,VISA 地址必须满足本地 allowed_resources 和 LAN 配置。清单更新不会关闭已打开的会话。

2026-11-16 加入 DSH 配置示例和设备清单接口。list_instruments 新增 connection_inventory 字段,已有调用参数保持兼容。

波形采用 x_origin_s、x_increment_s、values_v 和明确单位,避免重复传输时间轴。 实际硬件的二进制格式、字节序及纵轴换算必须在型号适配器中实现。 当前未提供可让模型任意发送字符串的 SCPI 工具。

开发与验证

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m build

测试覆盖模拟闭环、MCP stdio 客户端握手与调用、参数拒绝、USB/LAN 配置边界、 重复身份、失败清理、串行操作及二进制块错误。测试不连接实机。 GitHub Actions 在 Windows 和 Ubuntu 上运行检查。

src/rigol_lab_mcp/
  server.py       MCP 工具和资源
  service.py      会话、锁、执行证据、审计日志
  models.py       带单位的参数模型
  transport.py    USB/LAN VISA 及二进制块
  adapters.py     按厂商+型号精确注册适配器
  simulation.py  三类虚拟仪器
examples/         本地配置和演示
tests/            无硬件测试
docs/             型号接入说明与官方资料

后续请按 型号适配说明 补充驱动; 查阅 官方资料索引。

操作边界

参数回读表示仪器设置,不等于输出已经经过物理测量。通信失败后状态应视为未知; 本框架不自动重放写命令。二进制解析/通信异常会使该 VISA 会话失效,需重新连接。 关闭客户端、断开通信和进程退出都不承诺关闭物理输出;型号驱动和实验流程应显式处理。 真实输出的允许范围取决于接线、端接、衰减器与被测件,不能仅由仪器额定范围推导。

本地配置、日志和采样文件已加入 .gitignore。MIT 许可证只覆盖本仓库代码, RIGOL 手册链接对应的文档版权归各自所有者,本仓库不打包或再分发这些 PDF。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to control Rigol MSO5000 oscilloscopes through VISA, including acquisition, channels, trigger, timebase, waveform generator, display, and front-panel controls, with risk-based permission gating for direct SCPI operations.
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables LLMs to control RIGOL oscilloscopes over SCPI via LAN or USB, including configuring channels/timebase/trigger, taking measurements, capturing waveforms and screenshots, decoding serial protocols, running FFT analysis, and controlling the built-in AFG.
      38
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Puts PyVISA in front of AI tools so they can discover and drive oscilloscopes and other SCPI instruments over LAN, USB, GPIB, and serial. Builds a per-instrument local knowledge base from identity, manuals, and past commands, then exposes tools for SCPI queries, measurements, waveform capture and export, and scope configuration.
      22
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible AI clients to operate a RIGOL MHO98 oscilloscope over USB, including configuration, waveform and measurement acquisition, FFT analysis, and protocol decoding.
      16
      MIT