From a1f21dbc7a625461d3e3cea24ce5a1aa84a0a54a Mon Sep 17 00:00:00 2001 From: Scaxlibur <51772892+Scaxlibur@users.noreply.github.com> Date: Thu, 6 Aug 2026 16:59:09 +0800 Subject: [PATCH 1/4] docs: simplify project entry points --- README.md | 695 ++++++----------------------------------------- doc/README.md | 388 ++++---------------------- doc/README_EN.md | 127 +++------ plans/README.md | 63 +++++ 4 files changed, 244 insertions(+), 1029 deletions(-) create mode 100644 plans/README.md diff --git a/README.md b/README.md index 3efe13d..70f8ea2 100644 --- a/README.md +++ b/README.md @@ -1,657 +1,142 @@ # WaveBench -[English documentation](doc/README_EN.md) +[English documentation](doc/README_EN.md) · [中文文档总览](doc/README.md) · [仪器插件仓库](https://github.com/Scaxlibur/wavebench-instrument-plugins) > [!WARNING] -> 本项目仍处于早期开发阶段,会读写真实实验设备。错误操作可能导致器件、仪器损坏甚至人身伤害,使用时请务必小心。 - -WaveBench 是一个面向电子设计竞赛调试场景的轻量 Python 自动测量台。 - -它提供小而明确的 CLI 命令,用于控制局域网内的实验室仪器,也开始提供实验性的终端 TUI 控制面板。当前重点是可靠采集示波器波形、做信号源到示波器的闭环检查、控制可编程电源、读取万用表,以及用显式 run plan 编排多仪器实验。WaveBench 不做隐藏复位,也不偷偷打开或关闭输出。 - -WaveBench 主包长期预装 RTM2000/RTM2032、DS1104Z/DS1000Z、DG4000/DG4202、DP800 和 DM3000/DM3058 系列驱动;首次使用无需安装外置插件,只需复制示例配置并填写实际仪器 resource。这五个仪器族没有从主包移除的计划;外置插件是显式选择、独立发布的可选升级或扩展,不会取代示例配置使用的内建短名。 - -> [!TIP] -> 如需使用其他仪器,请移步[WaveBench插件专用仓库](https://github.com/Scaxlibur/wavebench-instrument-plugins)。 - -> [!IMPORTANT] -> 当前开发版本是 `v0.8.22`。`v0.8.22` 增加低阶预设谐波的 profile/configuration 模型、驱动协议和 capability-gated service 入口:公开写入仅限 EVEN、ODD、ALL;USER 位图与 H2–H16 幅度/相位仅供完整回读和恢复。只有具备逐字段回读、完整恢复和歧义写入锁存的外置插件才能声明这些能力,内建 DG4202 fallback 保持不声明;external modulation source、advanced digital modulation、用户自定义谐波与 DAC16 仍未公开。使用其他 Release 的读者应以对应 tag 内的文档和命令为准。 - -## 🌟 特别鸣谢 - -

- - LINUX DO - -

-

学AI,上L站!祝小破站越来越好~

- -## 当前能力 - -### 示波器:R&S RTM2032 与 RIGOL DS1104Z/DS1000Z - -- LAN VISA 连接 -- `scope idn`、`scope errors`;声明相应 capability 的驱动还支持只读 `scope status`、`scope acquisition-status`、`scope history-timestamps` 与 `scope measurement-statistics` -- 显式 `scope auto` / `scope autoscale` -- `scope fetch` 与 `scope capture`;默认先只读确认输入为高阻,50 Ω 需显式 `--allow-50ohm` -- 声明 `scope.capture_average` 的驱动可执行受控平均采集;公共结果要求逐项恢复并返回恢复前后配置证据 -- 声明 `scope.digital_status` 的驱动可读取既有 MSO 数字通道状态;该能力不读取数字波形,也不隐式配置阈值、显示或传输格式 -- 声明 `scope.digital_waveform` 的驱动可在调用方明确确认采集已停止后读取既有数字轨迹;返回值按 Dn→bit n 合并为 `uint16`,驱动不得改点数、传输格式、显示、阈值或采集状态 -- 通过重复 `--channel` 在一次 acquisition 中读取多通道;每个通道完成后立即原子落盘 -- DS1104Z 支持 CH1–CH4、NORM 屏幕波形、RAW 存储波形分块读取和 PNG 截图 -- DS1104Z 使用 `:WAVeform:PREamble?` 将 BYTE 数据换算为时间/电压;RAW 每块最多读取 250000 点 -- 采集包包含 NPY / CSV / JSON metadata / `commands.log` -- 波形指标:Vpp、RMS、均值、频率估计、占空比、适用时的上升/下降时间 -- 波形质量告警:周期数过少、每周期采样点过少、幅度过低、频率不匹配 - -### 信号源:RIGOL DG4202 - -- `source idn`、`source status` -- `source profile`:只读查询 basic 状态之外的负载、极性、噪声、同步、burst、调制、marker 与 pulse hold 上下文 -- `source sweep-profile`:只读查询仪器当前内置 sweep 的频率、时序、触发与 marker 全量 profile;不启动、停止或触发 sweep -- 公共 Python API 提供完整 sweep 配置事务与独立显式触发契约;具体驱动必须自行实施输出、负载、频率、回读、恢复与歧义写锁存边界。MANUAL 配置与触发必须通过同一个由调用方持有并关闭的持久 source session,临时会话会在连接仪器前拒绝这两种操作 -- `source counter-profile`:只读查询独立 counter 输入配置、统计状态及已有测量;不会自动启用 counter 或清除统计 -- `source set-freq` -- `source set-func`:`sin`、`squ`、`ramp`/`triangle`、`puls`、`nois`、`dc` -- `source set-vpp` -- `source set-duty` -- `source arb-probe`:只查询任意波 SCPI 支持情况 -- `source arb-load --dry-run`:离线校验任意波 payload -- `source arb-load --frequency ... --output-on`:已确认可用的 DG4202 `DATA:DAC VOLATILE` 任意波上传 -- `source output` -- `sweep discrete`:信号源到示波器的离散扫频,默认同样检查示波器高阻输入 -- 离散扫频可选 `--restore-source-state` 恢复 basic 信号源状态(输出、函数、频率、Vpp、方波占空比) - -### 电源:RIGOL DP800 系列 - -- `power idn`、`power status` -- `power protection status` -- `power protection set --ovp-threshold --ovp on|off --ocp-threshold --ocp on|off` -- `power set --voltage --current-limit` -- `power output on|off` -- 可配置读回等待: - - `power.settle_ms_after_set` - - `power.settle_ms_after_output` - - -### 万用表:RIGOL DM3000 / DM3058 系列 - -- `dmm idn` -- `dmm read dcv|acv|dci|aci|res|fres|freq|period|continuity|diode|cap` -- `dmm function status|set`、`dmm profile`:读取/设置当前测量功能,或只读当前量程码与 DCV 阻抗;不自动切换功能。 -- `dmm range set dcv|acv 0..4`、`dmm impedance set 10M|10G`:受控配置、回读和失败恢复;`10G` 仅允许 DCV 档位码 `0..2`。 -- `dmm trigger status`、`dmm calculation status`:只读当前触发与运算状态,不写设置、不清空统计、不触发测量。 -- `dmm system-interface status`:只读并脱敏输出蜂鸣器、语言、数字格式、亮度、选件状态、DHCP、GPIB 和 RS-232 状态;不查询设备/网络标识,也不写配置。 -- `dmm calculation statistics average|min|max --calculation-active-confirmed`:仅读取已启用且当前模式匹配的统计;调用者确认后驱动仍会复核模式。 -- 支持 DM3058 LAN/VISA 与 RS232 读取;RS232 可配置行终止符和流控,DM3058 实机基线为 9600 8N1、写 CRLF、读 LF、无流控。设备 SCPI 保留在 DMM driver,不进入 CLI / service。 -- 可配置 DMM 正式读取前等待:`dmm.settle_ms_before_read` -- 可用 `python scripts/dmm_dcv_staircase_smoke.py --config ` 对 `DP800 -> DMM` 做保守 DCV 阶梯 smoke,并自动恢复电源输出。 -- 可用 `python scripts/dmm_acv_source_smoke.py --config ` 对 `DG4202 -> DMM` 做保守 ACV/RMS smoke,并自动恢复信号源状态。 - - -### 终端 TUI:实验性控制面板 - -- TUI 是 `wavebench[tui]` optional extra;源码环境可用 `python -m pip install -e ".[tui]"` 安装界面依赖。 -- `tui`:启动 Textual 终端界面,默认读取当前目录的 `wavebench.toml`。 -- `tui --config `:从指定 TOML 读取仪器配置,适合不在配置文件目录启动时使用。 -- `tui --fake`:使用模拟电源、模拟万用表和模拟信号源,不连接真实仪器,适合检查界面。 -- `tui --refresh-interval 5`:设置自动刷新间隔;默认 5 秒。 -- `tui --log-file `:指定 TUI 调试日志文件;默认写入 `data/tui/wavebench-tui.log`。 -- TUI 持久日志行数限制可在 `[tui]` 中配置,默认超过 10000 行后保留最新 1000 行。 -- 电源面板支持三通道状态查看、设置电压/限流、开关输出、查看和设置 OVP/OCP。 -- 万用表面板支持常用挡位按钮切换和手动读取。 -- 信号源面板支持查看状态、设置波形/频率/幅度和切换输出。 -- 当前范围冻结为电源、万用表和信号源三个面板;核心能力以 CLI、run plan 和 Service 为准。TUI 不承担 run-plan 编排、插件管理、完整示波器波形查看或报告系统。 - -### 多仪器 run plan - -- `run check --plan `:只解析并汇总 plan,不连接仪器 -- `run verify --plan `:只读查询 plan 涉及仪器的高阻保护状态与 `*IDN?`,用于执行前预检可达性 -- `run template --list` / `run template --output `:列出或生成保守 run plan 模板;可用 `--frequency`、`--frequencies`、`--reference-channel`、`--response-channel`、`--fit` 等少量参数定制;不连接仪器,不覆盖已有文件,除非显式 `--force` -- `run plan --plan `:执行显式 source、power、scope、dmm、sleep 和双通道 `sweep.frequency_response` 步骤;一个 run 可有多个具唯一 label 的频响,每个响应可扫描二维 Vpp × 频率、软件直通基线、可选自适应频率加密,并导出浮点/定点校准 LUT;一次 run 内统一打开并复用所需仪器 session,成功或失败后统一关闭,不静默断线重连 -- `run calibrate --config [--response