# Rigol DP2031 程控上位机

**Repository Path**: mingkjl/rigoldp2031

## Basic Information

- **Project Name**: Rigol DP2031 程控上位机
- **Description**: ⚠️ 重要声明
本项目是个人开发的开源上位机，非 RIGOL 普源官方软件。
本软件基于SCPI协议实现对DP2301直流电源的程控控制，
使用风险由使用者自行承担。

- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DP2031 Python 驱动

本目录提供 RIGOL DP2031 三通道可编程线性直流电源的轻量 Python 驱动
`dp2031_driver.py`。驱动仅封装项目当前需要的常用功能，不覆盖编程手册中的全部
SCPI 命令，便于其他应用直接调用。

同时提供基于该驱动的图形界面上位机 `dp2031_ui.py`。

> 依据手册：`DP2031/DP2000_ProgrammingGuide_CN.pdf`（RIGOL DP2000 系列编程指南）。

## 支持的功能

| 功能 | Python 接口 | 对应 SCPI 命令 |
| --- | --- | --- |
| 扫描设备清单 | `scan_devices()` / `list_devices()` | VISA 资源枚举 + `*IDN?` |
| 连接设备 | `connect(id)` | 打开 USB / TCPIP VISA 资源 |
| 读取通道实时电压 | `measure_voltage(channel)` | `:MEAS? CH{n}` |
| 读取通道实时电流 | `measure_current(channel)` | `:MEAS:CURR? CH{n}` |
| 设置通道过压保护值 | `set_ovp(channel, value)` | `:OUTPut:OVP:VALue CH{n},value` |
| 设置通道过流保护值 | `set_ocp(channel, value)` | `:OUTPut:OCP:VALue CH{n},value` |
| 设置通道输出电压 | `set_voltage(channel, value)` | `:SOURce{n}:VOLTage value` |
| 设置通道输出电流 | `set_current(channel, value)` | `:SOURce{n}:CURRent value` |
| 打开/关闭过压保护 | `set_ovp_enabled(channel, enabled)` | `:OUTPut:OVP:STATe CH{n},ON/OFF` |
| 打开/关闭过流保护 | `set_ocp_enabled(channel, enabled)` | `:OUTPut:OCP:STATe CH{n},ON/OFF` |
| 打开/关闭指定通道 | `set_channel_enabled(channel, enabled)` | `:OUTPut:STATe CH{n},ON/OFF` |
| 查询指定通道开关状态 | `get_channel_enabled(channel)` | `:OUTPut:STATe? CH{n}` |
| 关闭所有通道 | `disable_all()` | `:OUTPut:STATe ALL,OFF` |

## 环境要求

- Python 3.9+
- 推荐安装 VISA 支持：

  ```powershell
  pip install pyvisa pyvisa-py
  ```

  其中：

  - `pyvisa` 是上层 Python VISA 接口；
  - `pyvisa-py` 是纯 Python 后端。如果电脑已安装 NI-VISA / RIGOL Ultra Sigma，
    驱动会优先使用系统 VISA，也可以不安装 `pyvisa-py`。

- USB 设备需要系统具备 USBTMC/VISA 驱动（安装 RIGOL Ultra Sigma 后通常自带 NI-VISA）。
- 如果仅使用 LAN 的 Raw Socket 资源
  `TCPIP0::<host>::<port>::SOCKET`，即使不安装 pyvisa，驱动也会退回 Python
  socket 直连。

- 图形界面上位机 `dp2031_ui.py` 使用 PySide6，需安装：

  ```powershell
  pip install PySide6
  ```

  也可以直接执行 `pip install -r requirements.txt` 一次安装全部依赖。

## 快速开始

### 图形界面上位机

```powershell
pip install -r requirements.txt
python dp2031_ui.py
```

界面说明：

- 左侧设备栏提供后台扫描、连接、断开、设备信息和“关闭全部通道”安全操作；
- CH1/CH2/CH3 仪表卡实时显示电压、电流、输出状态和最近设置值；
- 点击“保护设置”只设置 OVP/OCP 阈值及保护功能开关；
- 每个通道卡片直接提供输出电压、电流数位编辑器：点击个位或小数位后用右侧上下
  按钮调节，每次调节都会立即下发到设备；十位不可直接选择，只能通过个位操作自然
  进位或借位；
- 设置控件按编程手册中的 DP2031 默认档位可编程范围限制输入；
- 下方日志区域可拖动调整高度，并可一键清空。

### 面向对象的推荐用法

```python
import dp2031_driver as dp

# 1. 扫描设备清单，返回 DeviceInfo 列表
devices = dp.scan_devices()
print(devices)

if not devices:
    raise SystemExit("未扫描到 DP2031 设备")

# 2. 用扫描结果中的 id 连接设备
power = dp.connect(devices[0])

try:
    # 3. 读取 CH1 实时电压/电流
    voltage = power.measure_voltage(1)
    current = power.measure_current(1)
    print(f"CH1: {voltage:.4f} V, {current:.4f} A")

    # 4. 设置 CH1 输出值和过压/过流保护
    power.set_voltage(1, 12.0)
    power.set_current(1, 1.0)
    power.set_ovp(1, 33.0)
    power.set_ocp(1, 2.8)
    power.set_ovp_enabled(1, True)
    power.set_ocp_enabled(1, True)

    # 5. 打开 CH1
    power.set_channel_enabled(1, True)
    print("CH1 开关状态:", power.get_channel_enabled(1))

    # 6. 使用完毕后关闭所有通道
    power.disable_all()
finally:
    power.close()
```

### 模块级快捷函数用法

```python
import dp2031_driver as dp

devices = dp.scan_devices(interface="USB")
dp.connect(devices[0])

print(dp.measure_voltage(1))
dp.set_ovp(1, 33.0)
dp.enable_channel(1)
print(dp.get_channel_enabled(1))
dp.disable_all()
dp.close()
```

模块级函数内部只保留一个“默认连接”。需要同时控制多台设备时，请使用
`connect()` 返回的 `DP2031` 实例，不要混用模块级函数。

## 设备清单与连接 ID

`scan_devices()` 返回 `DeviceInfo` 列表。`DeviceInfo` 字段如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `resource` | `str` | VISA 资源名，也是传给 `connect()` 的设备 ID |
| `id` | `str` | `resource` 的只读别名 |
| `interface` | `str` | `"USB"` 或 `"TCPIP"` |
| `model` | `str` 或 `None` | 型号，例如 `DP2031` |
| `serial` | `str` 或 `None` | 序列号 |
| `firmware` | `str` 或 `None` | 软件版本 |
| `description` | `str` | 附加说明；扫描失败时会记录原因 |

调用 `info.as_dict()` 可得到适合 JSON 输出的字典。

常见的资源名示例：

- USB：`USB0::0x1AB1::0x0E11::DP2Dxxxxxxxxx::INSTR`
- LAN（VXI-11）：`TCPIP0::192.168.1.20::INSTR`
- LAN（Raw Socket）：`TCPIP0::192.168.1.20::5555::SOCKET`

也可以直接传入已知资源名：

```python
power = dp.connect("TCPIP0::192.168.1.20::INSTR")
```

## API 手册

### `scan_devices(interface=None, timeout_ms=1000, verify=True)`

扫描可见设备并返回清单。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `interface` | `str` 或 `None` | `None` | `"USB"`、`"TCPIP"`，或 `None` 表示全部 |
| `timeout_ms` | `int` | `1000` | 每台设备 `*IDN?` 查询超时 |
| `verify` | `bool` | `True` | 是否打开资源并查询 `*IDN?` 补全信息 |

返回：`List[DeviceInfo]`。

### `list_devices(*args, **kwargs)`

`scan_devices()` 的别名。

### `connect(device, timeout_ms=3000)`

连接指定设备并返回 `DP2031` 实例。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `device` | `str` / `DeviceInfo` / `dict` | 无 | 设备 ID（资源名）、`DeviceInfo` 或含 `id` 的字典 |
| `timeout_ms` | `int` | `3000` | 连接与查询超时 |

返回：`DP2031`。

### `DP2031.measure_voltage(channel) -> float`

读取指定通道实时输出电压，单位伏特（V）。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `channel` | `int` | 1、2 或 3 |

### `DP2031.measure_current(channel) -> float`

读取指定通道实时输出电流，单位安培（A）。

### `DP2031.set_ovp(channel, value)`

设置指定通道过压保护值，单位伏特（V）。

DP2031 默认档位下各通道 OVP 范围为：

- CH1/CH2（32 V/3 A）：1 mV 至 35.2 V，默认 35.2 V；
- CH3（6 V/5 A）：1 mV 至 6.6 V，默认 6.6 V。

> 注意：本接口只设置保护阈值，不会自动打开保护功能；请配合
> `set_ovp_enabled()` 使用。

### `DP2031.set_ocp(channel, value)`

设置指定通道过流保护值，单位安培（A）。

DP2031 默认档位下各通道 OCP 范围为：

- CH1/CH2：1 mA 至 3.3 A，默认 3.3 A；
- CH3：1 mA 至 5.5 A，默认 5.5 A。

> 同样地，本接口只设置保护阈值；请配合 `set_ocp_enabled()` 使用。

### `DP2031.set_voltage(channel, value)`

设置指定通道的输出电压设定值，单位伏特（V）。

### `DP2031.set_current(channel, value)`

设置指定通道的输出电流设定值，单位安培（A）。

### `DP2031.get_voltage_setting(channel) -> float` / `DP2031.get_current_setting(channel) -> float`

分别查询指定通道的输出电压、电流设定值。

### `DP2031.get_ovp(channel) -> float` / `DP2031.get_ocp(channel) -> float`

分别查询指定通道的过压保护值和过流保护值。

### `DP2031.set_ovp_enabled(channel, enabled)` / `DP2031.set_ocp_enabled(channel, enabled)`

打开或关闭指定通道的 OVP/OCP 保护功能。对应的
`get_ovp_enabled(channel)` / `get_ocp_enabled(channel)` 用于查询状态。

### `DP2031.set_channel_enabled(channel, enabled)`

打开或关闭指定通道输出。`enabled=True` 打开，`False` 关闭。

### `DP2031.enable_channel(channel)` / `DP2031.disable_channel(channel)`

`set_channel_enabled()` 的快捷封装。

### `DP2031.get_channel_enabled(channel) -> bool`

查询指定通道输出开关状态，返回 `True`（开）或 `False`（关）。

### `DP2031.disable_all()`

关闭所有通道输出。

### `DP2031.idn() -> str`

查询并返回设备标识字符串。

### `DP2031.close()`

关闭当前设备连接。也支持 `with` 语法：

```python
with dp.connect("USB0::...::INSTR") as power:
    print(power.measure_voltage(1))
```

## 模块级函数

以下函数作用于最近一次 `connect()` 建立的默认连接：

```text
scan_devices(...)          list_devices(...)
connect(device, ...)       close()
measure_voltage(channel)   measure_current(channel)
set_ovp(channel, value)    set_ocp(channel, value)
set_voltage(channel, value)  set_current(channel, value)
get_voltage_setting(channel)  get_current_setting(channel)
get_ovp(channel)  get_ocp(channel)
set_ovp_enabled(channel, enabled)  get_ovp_enabled(channel)
set_ocp_enabled(channel, enabled)  get_ocp_enabled(channel)
enable_channel(channel)    disable_channel(channel)
set_channel_enabled(channel, enabled)
get_channel_enabled(channel)
disable_all()
```

未连接时调用会抛出 `ConnectionError`。

## 通道与保护值参考

DP2031 三个输出通道（默认档位）：

| 通道 | 额定输出 | 电压可设范围 | 电流可设范围 | OVP 范围 | OCP 范围 |
| --- | --- | --- | --- | --- | --- |
| CH1 | 32 V / 3 A | 0 ~ 33.6 V | 0 ~ 3.15 A | 1 mV ~ 35.2 V | 1 mA ~ 3.3 A |
| CH2 | 32 V / 3 A | 0 ~ 33.6 V | 0 ~ 3.15 A | 1 mV ~ 35.2 V | 1 mA ~ 3.3 A |
| CH3 | 6 V / 5 A | 0 ~ 6.3 V | 0 ~ 5 A | 1 mV ~ 6.6 V | 1 mA ~ 5.5 A |

> “额定输出”与“SCPI 可编程范围”不是同一概念；上表的可设范围按编程手册
> 表 4.9/4.35 列出。安装 6 V/10 A 档位选件时，电流与 OCP 范围会变化。

## 异常类型

| 异常 | 说明 |
| --- | --- |
| `DP2031Error` | 驱动异常基类 |
| `ConnectionError` | 连接失败或连接已关闭 |
| `DependencyError` | 缺少 VISA 依赖（通常需要安装 `pyvisa`） |
| `CommandError` | SCPI 命令失败或返回值解析失败 |
| `DeviceNotFoundError` | 未找到设备（预留异常，扫描返回空列表） |

## 实现说明

- USB 连接依赖 VISA/USBTMC，驱动优先使用系统 VISA，其次使用 `pyvisa-py`。
- TCPIP 连接优先使用 VISA；未安装 pyvisa 时会尝试内置 socket 直连，
  默认 Raw Socket 端口为 5555。
- 所有 SCPI 命令均以 `\n` 结尾；查询返回前会去除首尾空白。
- 通道号在调用前统一校验，仅接受 1、2、3。

## 注意事项

- 打开通道输出前，请确认电压/电流设置不会对被测设备造成损坏。
- 关闭所有通道不会复位电压、电流及保护值设置。
- 设置过压/过流保护值不等同于打开保护功能，请按实际需求配置保护开关。
- 多通道联机（串联/并联/跟踪）不属于本驱动当前封装范围。

## USBTMC 通信排障

若日志出现 `VI_ERROR_INP_PROT_VIOL (-1073807305)`：

- 先关闭已运行的本上位机、NI MAX 测试面板、Ultra Sigma 或其他正在访问该电源的软件，
  确保同一时间只有一个 VISA 会话控制设备；
- 再重新运行 `python dp2031_ui.py`。驱动会在查询前保留 50 ms 处理时间，并在该协议错误
  发生时自动执行 VISA Clear 和最多两次重试；
- 如果仍持续失败，请重新插拔 USB 线、重启电源，并确认 NI-VISA 和 DP2031 固件为可用的
  最新版本；也可以改用 LAN/VXI-11 连接以区分 USBTMC 与 SCPI/API 问题。