内容
# Rigol DHO800/DHO900 MCP 服务器
Rigol DHO800/DHO900 系列示波器的 MCP（Model Context Protocol）服务器，基于官方编程指南中的 SCPI 命令集构建。它直接与示波器的原始 SCPI 套接字（端口 5555）通信，因此无需安装 VISA。
## 工具列表
| 工具 | 用途 |
|---|---|
| `identify` | `*IDN?`，用于验证连接性和获取型号/序列号/固件 |
| `get_status` | 触发状态、采样率、内存深度、时基、每通道设置 |
| `run_control` | 运行/停止/单次/自动设置/清除/强制触发 |
| `configure_channel` | 使能、V/div、偏移、耦合、探头比率、带宽限制、反转 |
| `configure_timebase` | 主时基刻度和偏移 |
| `configure_trigger_edge` | 边沿触发源、斜率、级别、扫描模式 |
| `configure_acquisition` | 内存深度、采集类型、平均值 |
| `get_measurement` | 自动测量（VPP、VRMS、频率、时间等） |
| `get_waveform` | 屏幕或深内存的缩放电压/时间数据，带统计信息 |
| `get_screenshot` | 示波器显示的 PNG 图片 |
| `scpi_command` | 原始 SCPI 命令的逃脱口，用于指南中的其他命令 |
| `configure_cursors` | 设置光标模式（OFF/MANual/TRACk）、类型、源和位置 |
| `get_cursor_values` | 读取光标位置和增量/频率读数 |
| `measure_between` | 两个通道之间的延迟或相位（RRDelay、FFPHase 等） |
## 示波器设置
1. 将示波器连接到您的局域网，并在示波器的 `Utility > IO` 下获取其 IP 地址。
2. 就是这样。端口 5555 上的原始 SCPI 套接字默认情况下是开放的。
## 在本地运行（stdio）
```bash
pip install .
RIGOL_HOST=192.168.1.100 rigol-dho-mcp
```
这会在 stdio 上启动服务器，准备好让任何 MCP 客户端生成并直接与其通信。
## 在本地测试 SCPI 命令（CLI）
`rigol-dho-cli` 直接通过与 MCP 服务器相同的 SCPI 客户端与示波器通信，无需 MCP 客户端。便于检查命令是否有效，或在将其作为工具连接之前调试连接。
```bash
pip install .
# 一次性：运行一个或多个命令并打印结果，然后退出
RIGOL_HOST=192.168.1.100 rigol-dho-cli "*IDN?" ":CHANnel1:SCALe?"
# 交互式 REPL：省略命令
RIGOL_HOST=192.168.1.100 rigol-dho-cli
scpi> *IDN?
RIGOL TECHNOLOGIES,DHO814,...
scpi> :RUN
OK （系统错误队列：0,"No error"）
scpi> :DISPlay:DATA? PNG
二进制响应（34521 字节）-> 保存到 capture_00001.png
scpi> quit
```
它读取与服务器相同的 `RIGOL_HOST` / `RIGOL_PORT` / `RIGOL_TIMEOUT` 环境变量（或直接传递 `--host` / `--port` / `--timeout`）。查询（以 `?` 结尾的命令）会打印响应；写入后会跟随 `:SYSTem:ERRor?` 检查，以便立即显示输入错误。 二进制响应（截图、波形数据）会保存到当前目录的文件中，而不是转储到终端。
## 使用 Docker 运行
### HTTP 传输（推荐用于容器）
```bash
docker build -t rigol-dho-mcp .
docker run -d --name rigol-dho-mcp \
-p 8000:8000 \
-e RIGOL_HOST=192.168.1.100 \
rigol-dho-mcp
```
这会将 MCP 端点暴露在 `http://<docker-host>:8000/mcp`（可流式 HTTP）。
#### 使用 Docker Compose
或者，您可以使用 `docker-compose.yml`:
```bash
# 复制示例环境文件并使用示波器的 IP 地址编辑它：
cp .env.example .env
# 编辑 .env 以在 RIGOL_HOST 下设置示波器的 IP 地址
# 然后启动服务：
docker compose up -d
# 查看日志：
docker compose logs -f
# 停止服务：
docker compose down
```
### Docker 内部的 stdio
```bash
docker run -i --rm \
-e RIGOL_HOST=192.168.1.100 \
-e MCP_TRANSPORT=stdio \
rigol-dho-mcp
```
> 容器需要能够访问示波器的 IP 地址。在 Linux 上，默认桥接网络通常效果很好；如果您的示波器仅位于主机的 LAN 段上，而桥接路由无法到达它，请添加 `--network host`。对于 docker-compose，您可以在 `docker-compose.yml` 中取消注释 `network_mode: "host"` 行。
## 与 MCP 客户端一起使用
这是一个标准的 MCP 服务器，因此任何支持通过 stdio 或可流式 HTTP 的 MCP 的客户端都可以使用它。配置格式基本相同：在任何地方，指向 `rigol-dho-mcp` 命令（stdio）或正在运行的 HTTP 端点，并传递 `RIGOL_HOST`。
**stdio：**
```json
{
"mcpServers": {
"rigol-dho800": {
"command": "rigol-dho-mcp",
"env": { "RIGOL_HOST": "192.168.1.100" }
}
}
}
```
**流式 HTTP** （从上面指向 Dockerized 服务器）：
```json
{
"mcpServers": {
"rigol-dho800": {
"url": "http://localhost:8000/mcp"
}
}
}
```
如果您的客户端不支持原生远程 MCP 服务器，请使用 `mcp-remote` 作为桥梁：
```json
{
"mcpServers": {
"rigol-dho800": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:8000/mcp"]
}
}
}
```
查看客户端文档，了解此配置的确切位置；值本身不会更改。
## 环境变量
| 变量 | 默认值 | 含义 |
|---|---|---|
| `RIGOL_HOST` | — （必填） | 示波器 IP 地址或主机名 |
| `RIGOL_PORT` | `5555` | SCPI 套接字端口 |
| `RIGOL_TIMEOUT` | `10` | I/O 超时，秒 |
| `MCP_TRANSPORT` | `stdio` （本地）/ `streamable-http` （Docker） | 传输 |
| `MCP_HOST` / `MCP_PORT` | `0.0.0.0` / `8000` | HTTP 绑定地址/端口 |
| `RIGOL_ENABLE_SCPI_RAW` | `0` | 设置为 `1` 以公开 `scpi_command` （默认关闭） |
## 注意
- 深内存读取（`get_waveform` with `mode="memory"`）需要示波器处于 STOP 状态，因此请先调用 `run_control("stop")`。数据以块返回，并在返回前减少到 `max_points`。
- 波形样本使用前缀按伏特缩放：`V = (raw − YORigin − YREFerence) × YINCrement`。
- 接近 `9.9e37` 的测量值表示它对于当前信号无效。`get_measurement` 为您标记了这一点。
- `scpi_command` 是按需开启的（设置 `RIGOL_ENABLE_SCPI_RAW=1`）。它在仅写入命令后检查 `:SYSTem:ERRor?`，因此原始 SCPI 中的输入错误会立即显示，而不是静默失败。
