RIGOL Lab MCP
by WindSweeps
README.md
# RIGOL Lab MCP
让 AI 通过结构化工具连接实验仪器的 Python / MCP 框架。优先支持 USB,预留 LAN;
射频源、函数/任意波形发生器和示波器共用设备管理、参数模型和通信层。
**当前为框架版本,真实仪器仅支持发现、连接和身份查询。具体型号驱动尚未加入。**
完整的设置、输出和测量流程已在模拟设备中实现。模拟值不代表实测结果。
本项目与 RIGOL 无隶属关系。
## 支持范围
| 功能 | 当前状态 |
| --- | --- |
| MCP stdio 服务、类型化工具、设备能力查询 | 已实现 |
| USB VISA 资源发现、连接、读取 *IDN? | 已实现;尚未经过实机验证 |
| LAN TCPIP INSTR / SOCKET 入口 | 已实现,显式配置启用;尚未经过实机验证 |
| 真实型号的输出、采集和测量命令 | 等待具体型号及固件信息 |
| 模拟射频源、信号发生器、示波器 | 已实现 |
| 同一设备串行操作、超时、连接清理、可选操作日志 | 已实现 |
| 有长度限制的 IEEE 488.2 二进制块读取 | 已实现,供后续驱动使用 |
## 安装
需要 Python 3.11+。在 Windows PowerShell 中:
~~~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 加载
[配置文件](examples/dsh.patch.yml):
~~~sh
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 的客户端中添加以下配置,替换为你的实际绝对路径:
~~~json
{
"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。
~~~powershell
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 后端:
~~~powershell
.\.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`,提交完整清单:
~~~json
{
"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 工具。
## 开发与验证
~~~powershell
.\.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 上运行检查。
~~~text
src/rigol_lab_mcp/
server.py MCP 工具和资源
service.py 会话、锁、执行证据、审计日志
models.py 带单位的参数模型
transport.py USB/LAN VISA 及二进制块
adapters.py 按厂商+型号精确注册适配器
simulation.py 三类虚拟仪器
examples/ 本地配置和演示
tests/ 无硬件测试
docs/ 型号接入说明与官方资料
~~~
后续请按 [型号适配说明](docs/adapters.md) 补充驱动;
查阅 [官方资料索引](docs/sources.md)。
## 操作边界
参数回读表示仪器设置,不等于输出已经经过物理测量。通信失败后状态应视为未知;
本框架不自动重放写命令。二进制解析/通信异常会使该 VISA 会话失效,需重新连接。
关闭客户端、断开通信和进程退出都不承诺关闭物理输出;型号驱动和实验流程应显式处理。
真实输出的允许范围取决于接线、端接、衰减器与被测件,不能仅由仪器额定范围推导。
本地配置、日志和采样文件已加入 .gitignore。MIT 许可证只覆盖本仓库代码,
RIGOL 手册链接对应的文档版权归各自所有者,本仓库不打包或再分发这些 PDF。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues