feat: 加入了一系列调试和分析工具,包括 SCPI REPL、示波器数据查看器、声速检测器等,方便开发和实验调试。

fix: 修复实验页面中实验状态未正确更新的问题,确保实验状态在前端和后端之间保持一致。
docs: 添加了SCPI文档和总程序设计架构
这个提交包含在:
2026-06-25 18:29:31 +08:00
父节点 61b20ca200
当前提交 c742cc7070
共有 24 个文件被更改,包括 9263 次插入 和 5 次删除

2838
backend/SCPI.md 普通文件

文件差异内容过多而无法显示 加载差异

查看文件

@ -139,3 +139,28 @@ async def clear_all_field_values(x_session_id: str | None = Header(default=None)
session_id = resolve_session_id(x_session_id) session_id = resolve_session_id(x_session_id)
removed_count = session_store.clear(session_id) removed_count = session_store.clear(session_id)
return {"message": f"cleared {removed_count} field values", "success": True, "session_id": session_id} return {"message": f"cleared {removed_count} field values", "success": True, "session_id": session_id}
@router.post("/reset")
async def reset_experiment(
experiment: str = Query(default="cn.edu.muc.lxy.phyexp.voicespeed"),
x_session_id: str | None = Header(default=None),
):
session_id = resolve_session_id(x_session_id)
session_store.clear(session_id)
reading_guard_manager.reset_session(session_id)
all_fields = list_fields(experiment)
guard_fields = [
f.fieldId for f in all_fields
if f.readingGuard is not None and f.readingGuard.enabled
]
ctrl = _peak_monitor_status_text(session_id)
return {
"success": True,
"message": "experiment state reset",
"session_id": session_id,
"pending_field": guard_fields[0] if guard_fields else None,
"cursor": 0,
"total": len(guard_fields),
"control_status": ctrl,
}

查看文件

@ -67,6 +67,10 @@ class ReadingGuardManager:
src = state.source.value if isinstance(state.source, ReadingGuardSource) else str(state.source) src = state.source.value if isinstance(state.source, ReadingGuardSource) else str(state.source)
return (state.pending_field, src, state.tolerance) return (state.pending_field, src, state.tolerance)
def reset_session(self, session_id: str) -> None:
with self._lock:
self._sessions.pop(session_id, None)
def get_cursor(self, session_id: str) -> tuple[int, int]: def get_cursor(self, session_id: str) -> tuple[int, int]:
with self._lock: with self._lock:
state = self._sessions.get(session_id) state = self._sessions.get(session_id)
@ -233,8 +237,19 @@ class ReadingGuardManager:
state.pending_answer = self._capture_answer(state.source, current_field.fieldId, state) state.pending_answer = self._capture_answer(state.source, current_field.fieldId, state)
if state.pending_answer is None: if state.pending_answer is None:
source_label = "OCR" if state.source == ReadingGuardSource.PEAK_OCR else "standard reading" if state.source in (ReadingGuardSource.DEVICE_PEAK, ReadingGuardSource.DEVICE_FREQUENCY):
return {"accept": False, "message": f"{source_label} not yet captured, please wait for peak detection or retry", "severity": "error", "reference": None} state.cursor += 1
fields_map = {f.fieldId: f for f in all_fields}
self._arm_next(state, fields_map)
return {
"accept": True,
"message": f"设备离线,无法获取参考读数,已直接记录。等待下一个: {state.pending_field or '完成'}",
"severity": "warning",
"reference": None,
}
if state.source == ReadingGuardSource.PEAK_OCR:
return {"accept": False, "message": "OCR not yet captured, please wait for peak detection or retry", "severity": "error", "reference": None}
return {"accept": False, "message": f"manual reference for '{current_field.fieldId}' not yet set", "severity": "error", "reference": None}
try: try:
student_value = float(current_value) student_value = float(current_value)

二进制
backend/chart.png 普通文件

二进制文件未显示。

之后

宽度:  |  高度:  |  大小: 44 KiB

二进制
backend/chart2.png 普通文件

二进制文件未显示。

之后

宽度:  |  高度:  |  大小: 58 KiB

查看文件

@ -7,7 +7,13 @@ requires-python = ">=3.10"
dependencies = [ dependencies = [
"fastapi[standard]>=0.116.1", "fastapi[standard]>=0.116.1",
"libusb>=1.0.29.post7", "libusb>=1.0.29.post7",
"matplotlib>=3.10.9",
"numpy>=2.2.6",
"pillow>=12.2.0",
"pydantic>=2.11.3", "pydantic>=2.11.3",
"pyqt5>=5.15.11",
"pyqtgraph>=0.14.0",
"pyusb>=1.3.1", "pyusb>=1.3.1",
"scipy>=1.15.3",
"uvicorn>=0.35.0", "uvicorn>=0.35.0",
] ]

304
backend/tools/ch2_plotter.py 普通文件
查看文件

@ -0,0 +1,304 @@
#!/usr/bin/env python3
"""
CH2 实时数据绘图器 — 接收 ch2_recorder.py 的 stdout 管道,实时绘制测量值曲线。
用法:
python ch2_recorder.py -i 200 -n 100 | python ch2_plotter.py
python ch2_recorder.py -i 200 | python ch2_plotter.py --fields pkpk_v,avg_v,rms_v
python ch2_recorder.py -i 200 -n 50 | python ch2_plotter.py -o chart.png
python ch2_plotter.py --file ch2_log.jsonl # 读取已有日志
特性:
- 从 stdin 逐行读取 JSON,实时更新多子图曲线
- 支持 --fields 选择绘图字段,默认全绘
- 支持 --window 设置滚动窗口(秒),0 表示不滚动
- 支持 --output 保存最终图像
- 支持 --file 读取已有日志文件回放
"""
from __future__ import annotations
import argparse
import json
import select
import sys
import time
from collections import defaultdict
from dataclasses import dataclass, field
from typing import Optional
import matplotlib
import matplotlib.pyplot as plt
import numpy as np
# ─── 字段分组 ────────────────────────────────────────────────────
# 字段 → (子图标题, 单位)
FIELD_GROUPS: dict[str, tuple[str, str]] = {
# Voltage group
"max_v": ("Voltage (V)", "V"),
"min_v": ("Voltage (V)", "V"),
"pkpk_v": ("Voltage (V)", "V"),
"vtop_v": ("Voltage (V)", "V"),
"vbase_v": ("Voltage (V)", "V"),
"vamp_v": ("Voltage (V)", "V"),
"avg_v": ("Voltage (V)", "V"),
"rms_v": ("Voltage (V)", "V"),
"cycrms_v": ("Voltage (V)", "V"),
"curs_rms_v": ("Voltage (V)", "V"),
"std_v": ("Voltage (V)", "V"),
# Time/Freq group
"period": ("Time / Freq", "s"),
"freq": ("Time / Freq", "Hz"),
# Misc
"num_points": ("Points", ""),
"vdiv": ("Scale", "V/div"),
"offset_v": ("Offset (V)", "V"),
}
# 默认颜色循环
_COLORS = [
"#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd",
"#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf",
]
# 字段 → 颜色(保持稳定)
_field_colors: dict[str, str] = {}
_color_idx = 0
def _get_color(field: str) -> str:
global _color_idx
if field not in _field_colors:
_field_colors[field] = _COLORS[_color_idx % len(_COLORS)]
_color_idx += 1
return _field_colors[field]
# ─── 数据结构 ────────────────────────────────────────────────────
@dataclass
class PlotterState:
window_sec: float = 0.0
times: list[float] = field(default_factory=list)
data: dict = field(default_factory=lambda: defaultdict(list))
start_time: Optional[float] = None
fig: Optional[object] = None # plt.Figure
axes: dict = field(default_factory=dict) # {str: plt.Axes}
lines: dict = field(default_factory=dict) # {str: plt.Line2D}
fields: list[str] = field(default_factory=list)
def init_figure(self):
group_names = []
seen = set()
for f in self.fields:
g = FIELD_GROUPS.get(f, ("其他", ""))[0]
if g not in seen:
group_names.append(g)
seen.add(g)
nrows = len(group_names)
self.fig, axs = plt.subplots(nrows, 1, figsize=(14, 2.5 * nrows),
sharex=True, squeeze=False)
self.fig.canvas.manager.set_window_title("CH2 Real-time Monitor")
for i, gname in enumerate(group_names):
ax = axs[i][0]
ax.set_ylabel(gname)
ax.grid(True, alpha=0.3)
self.axes[gname] = ax
if group_names:
axs[-1][0].set_xlabel("Time (s)")
# 初始化空线
for f in self.fields:
gname = FIELD_GROUPS.get(f, ("其他", ""))[0]
unit = FIELD_GROUPS.get(f, ("", ""))[1]
label = f"{f}"
if unit:
label += f" [{unit}]"
(line,) = self.axes[gname].plot(
[], [], label=label, color=_get_color(f), linewidth=1.2
)
self.lines[f] = line
self.axes[gname].legend(loc="upper right", fontsize=7)
plt.tight_layout()
def append(self, record: dict) -> int:
ts = record.get("timestamp", time.time())
if self.start_time is None:
self.start_time = ts
rel_time = ts - self.start_time
self.times.append(rel_time)
for f in self.fields:
val = record.get(f)
self.data[f].append(val if val is not None else np.nan)
if self.window_sec > 0 and len(self.times) > 1:
cutoff = rel_time - self.window_sec
while len(self.times) > 1 and self.times[0] < cutoff:
self.times.pop(0)
for f in self.fields:
self.data[f].pop(0)
return len(self.times)
def update_plot(self) -> bool:
if not self.fig or not self.times:
return False
for f in self.fields:
line = self.lines.get(f)
if line is None:
continue
xs = np.array(self.times)
ys = np.array(self.data[f], dtype=np.float64)
line.set_data(xs, ys)
for ax in self.axes.values():
ax.relim()
ax.autoscale_view(scaley=True)
gname = list(self.axes.keys())[-1] if self.axes else None
if gname:
self.axes[gname].relim()
self.axes[gname].autoscale_view(scalex=True)
self.fig.canvas.draw_idle()
self.fig.canvas.flush_events()
return True
# ─── 主逻辑 ──────────────────────────────────────────────────────
def _parse_fields_arg(raw: Optional[str]) -> list[str]:
if raw is None:
# 默认绘制所有电压 + 时间/频率字段
defaults = ["pkpk_v", "avg_v", "rms_v", "max_v", "min_v"]
return defaults
return [f.strip() for f in raw.split(",") if f.strip()]
def _is_interactive() -> bool:
return matplotlib.get_backend().lower() != "agg"
def _read_stream(stream, state: PlotterState, pause_sec: float = 0.05):
"""从流中逐行读取 JSON,实时更新绘图。"""
buf = ""
update_every = 3 # 每 N 条数据刷新一次图
interactive = _is_interactive()
if interactive:
plt.ion()
state.init_figure()
plt.show(block=False)
else:
state.init_figure()
count = 0
try:
while True:
if stream is sys.stdin:
# 用 select 检查是否有数据可读
ready, _, _ = select.select([sys.stdin], [], [], 0.1)
if not ready:
# 无数据时也刷新图
if count > 0:
state.update_plot()
continue
chunk = sys.stdin.read(4096)
if not chunk:
break
else:
chunk = stream.read(4096)
if not chunk:
break
buf += chunk
while "\n" in buf:
line, buf = buf.split("\n", 1)
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
except json.JSONDecodeError:
# 跳过分隔行 (如 stderr 的日志混入)
continue
count = state.append(record)
if count % update_every == 0:
state.update_plot()
except KeyboardInterrupt:
pass
finally:
state.update_plot()
def main():
parser = argparse.ArgumentParser(
description="CH2 实时数据绘图器 — 接收 ch2_recorder.py 管道输出并实时绘图",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
示例:
python ch2_recorder.py -i 200 | python ch2_plotter.py
python ch2_recorder.py -i 200 | python ch2_plotter.py -f pkpk_v,avg_v,rms_v,freq
python ch2_plotter.py --file ch2_log.jsonl -o chart.png
python ch2_recorder.py -i 200 -n 500 | python ch2_plotter.py -w 30 -o result.png
""",
)
parser.add_argument(
"-f", "--fields", type=str, default=None,
help="要绘制的字段,逗号分隔 (默认: pkpk_v,avg_v,rms_v,max_v,min_v)",
)
parser.add_argument(
"-w", "--window", type=float, default=0.0,
help="滚动时间窗口 (秒),0 表示显示全部数据 (默认 0)",
)
parser.add_argument(
"-o", "--output", type=str, default=None,
help="保存最终图像到文件 (PNG/SVG/PDF),不指定则仅显示",
)
parser.add_argument(
"--file", type=str, default=None,
help="读取已有 JSONL 日志文件(而非 stdin 管道)",
)
parser.add_argument(
"--backend", type=str, default=None,
help="matplotlib 后端 (如 TkAgg, Qt5Agg, Agg),默认自动选择",
)
args = parser.parse_args()
if args.backend:
matplotlib.use(args.backend)
fields = _parse_fields_arg(args.fields)
state = PlotterState(window_sec=args.window, fields=fields)
if args.file:
with open(args.file, "r") as f:
_read_stream(f, state)
else:
_read_stream(sys.stdin, state)
if args.output:
state.fig.savefig(args.output, dpi=150, bbox_inches="tight")
print(f"\n[INFO] Chart saved: {args.output}", file=sys.stderr)
print(f"\n[INFO] Total data points: {len(state.times)}", file=sys.stderr)
if _is_interactive():
try:
plt.show(block=True)
except KeyboardInterrupt:
pass
if __name__ == "__main__":
main()

查看文件

@ -0,0 +1,746 @@
#!/usr/bin/env python3
"""
CH2 通道实时数据采集记录器 (NDS202E / NDS102U 兼容)
通过原生 PyUSB (libusb) + SCPI 协议与 OWON 示波器通信,
按可配置的采样间隔获取 CH2 通道的测量值 (min/max/pkpk/avg/rms 等),
并打上时间戳记录。
基于实际 NDS202E (V5.1.0) 固件调研结果,适配了真实返回格式:
- 所有响应以 "->\\n" 结尾
- HEAD JSON 使用全大写 key (TIMEBASE/CHANNEL/...)
- :MEASUrement 单项返回格式如 "Ma : 12.00V->"
- :MEASUrement:CH2? 返回 JSON (含 \\t? 表示无效值)
用法:
python ch2_recorder.py # 默认 500ms 间隔,stdout (JSON)
python ch2_recorder.py -i 200 -o ch2.csv # 200ms 间隔,CSV 文件
python ch2_recorder.py -i 100 -n 100 # 100ms 间隔,采集 100 次
python ch2_recorder.py --mode measure # 硬件测量模式 (实时,推荐)
python ch2_recorder.py --mode waveform # 数据接口 + 软件计算 (需强制触发)
"""
from __future__ import annotations
import argparse
import csv
import json
import re
import signal
import struct
import sys
import time
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import Optional
import numpy as np
import usb.core
import usb.util
# ─── 常量 ─────────────────────────────────────────────────────────
DEFAULT_VID = 0x5345
DEFAULT_PID = 0x1234
DEFAULT_TIMEOUT_MS = 5000
_DEFAULT_INTERVAL_MS = 500
# 电压换算
_SCREEN_DIVS_V = 8 # 垂直分度数
_ADC_MAX = 0x1000 # 12-bit = 4096
# 响应后缀: NDS202E V5.1.0 所有查询响应以 "->\\n" 结尾
_RESP_SUFFIX = re.compile(rb'\s*->\s*$')
_SCALE_RE = re.compile(r"([\d.]+)\s*([numk]?[sv])\s*", re.IGNORECASE)
_UNIT_MULTIPLIERS: dict[str, float] = {
"nv": 1e-9, "uv": 1e-6, "mv": 1e-3, "v": 1.0, "kv": 1e3,
"ns": 1e-9, "us": 1e-6, "ms": 1e-3, "s": 1.0, "ks": 1e3,
}
_NUMERIC_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")
# ─── 解析工具 ────────────────────────────────────────────────────
def parse_scale_str(raw: str) -> float:
m = _SCALE_RE.search(raw.lower().strip())
if m:
return float(m.group(1)) * _UNIT_MULTIPLIERS.get(m.group(2), 1.0)
try:
return float(raw)
except (ValueError, TypeError):
return 1.0
def parse_probe_ratio(raw: str) -> float:
try:
return float(raw.strip().lower().rstrip("x"))
except (ValueError, TypeError):
return 1.0
def strip_resp_suffix(data: bytes) -> bytes:
"""去除 NDS202E 响应末尾的 '->' 后缀。"""
return _RESP_SUFFIX.sub(b'', data)
def extract_numeric(text: str) -> Optional[float]:
m = _NUMERIC_RE.search(text)
if m is None:
return None
try:
return float(m.group())
except (ValueError, OverflowError):
return None
def clean_meas_text(text: str) -> str:
"""清理测量响应文本: 去掉前缀标签 + 单位后缀, 仅保留数值。"""
# 格式如 "Ma : 12.00V->" → "12.00"
# "Vpp: 24.00V->" → "24.00"
# "V : 1.892V->" → "1.892"
# "T: 26.920us->" → "26.920"
# "F: 37.15KHz->" → "37.15"
# "Vt : \t?->" → None (无有效值)
text = text.strip()
# 去掉 "->" 后缀
if text.endswith("->"):
text = text[:-2].strip()
# 提取数值部分
val = extract_numeric(text)
return str(val) if val is not None else ""
# ─── USB SCPI 通信(原生 PyUSB)─────────────────────────────────
class ScpiDevice:
"""原生 PyUSB SCPI 通信器 — 直接操作 USB 批量端点。"""
def __init__(self, vid: int = DEFAULT_VID, pid: int = DEFAULT_PID):
self._vid = vid
self._pid = pid
self._dev: Optional[usb.core.Device] = None
self._ep_out: Optional[usb.core.Endpoint] = None
self._ep_in: Optional[usb.core.Endpoint] = None
self._max_pkt: int = 512
self._detached: list[int] = []
def open(self):
dev = usb.core.find(idVendor=self._vid, idProduct=self._pid)
if dev is None:
raise RuntimeError(
f"设备未找到 (VID=0x{self._vid:04X}, PID=0x{self._pid:04X})"
)
self._dev = dev
for cfg in self._dev:
for intf in cfg:
ifn = intf.bInterfaceNumber
if self._dev.is_kernel_driver_active(ifn):
self._dev.detach_kernel_driver(ifn)
self._detached.append(ifn)
self._dev.set_configuration()
intf = self._dev.get_active_configuration()[(0, 0)]
for ep in intf:
dir_ = usb.util.endpoint_direction(ep.bEndpointAddress)
if dir_ == usb.util.ENDPOINT_OUT:
self._ep_out = ep
elif dir_ == usb.util.ENDPOINT_IN:
self._ep_in = ep
if not self._ep_out or not self._ep_in:
raise RuntimeError("未找到批量端点")
self._max_pkt = self._ep_in.wMaxPacketSize
def close(self):
if self._dev is None:
return
for ifn in self._detached:
try:
self._dev.attach_kernel_driver(ifn)
except usb.core.USBError:
pass
self._detached.clear()
try:
usb.util.dispose_resources(self._dev)
except Exception:
pass
self._dev = None
self._ep_out = None
self._ep_in = None
def __enter__(self):
self.open()
return self
def __exit__(self, *args):
self.close()
def write(self, cmd: bytes, timeout: int = DEFAULT_TIMEOUT_MS) -> None:
self._dev.write(self._ep_out, cmd, timeout=timeout)
def read(self, timeout: int = DEFAULT_TIMEOUT_MS) -> bytes:
resp = b""
while True:
try:
data = self._dev.read(self._ep_in, self._max_pkt, timeout=timeout)
if not data:
break
resp += data.tobytes()
if len(data) < self._max_pkt:
break
except usb.core.USBError as e:
if e.errno == 110:
break
raise
return resp
def flush_input(self) -> None:
try:
while True:
self._dev.read(self._ep_in, self._max_pkt, timeout=50)
except usb.core.USBError:
pass
def send(self, scpi: str, timeout: int = DEFAULT_TIMEOUT_MS) -> bytes:
"""发送 SCPI 命令,返回去除后缀的原始响应。"""
if not scpi.endswith("\n"):
scpi += "\n"
self.flush_input()
self.write(scpi.encode("ascii"), timeout=timeout)
raw = self.read(timeout=timeout)
return strip_resp_suffix(raw)
def send_text(self, scpi: str, timeout: int = DEFAULT_TIMEOUT_MS) -> str:
"""发送 SCPI 查询命令,返回解码后的文本。"""
return self.send(scpi, timeout).decode("ascii", errors="ignore").strip()
def write_cmd(self, scpi: str, timeout: int = DEFAULT_TIMEOUT_MS) -> None:
"""发送 SCPI 设置命令(无返回值,不等待响应)。"""
if not scpi.endswith("\n"):
scpi += "\n"
self.flush_input()
self.write(scpi.encode("ascii"), timeout=timeout)
def idn(self) -> str:
return self.send_text("*IDN?")
# ─── HEAD 解析 (适配 NDS202E 全大写 JSON) ───────────────────────
@dataclass
class ChannelParams:
name: str = ""
display: bool = True
coupling: str = "dc"
probe: str = "1x"
scale: str = "1v"
offset_head: int = 0 # HEAD 中的 OFFSET (单位: 1/250 div, NDS202E)
offset_volts: float = 0.0 # SCPI 查询得到的实际电压偏移
inverse: bool = False
@property
def vdiv(self) -> float:
return parse_scale_str(self.scale)
@property
def probe_ratio(self) -> float:
return parse_probe_ratio(self.probe)
def fetch_head(dev: ScpiDevice) -> Optional[dict]:
resp = dev.send(":DATA:WAVE:SCREen:HEAD?")
if not resp or len(resp) < 4:
return None
payload_len = struct.unpack("<I", resp[:4])[0]
payload = resp[4:]
if len(payload) != payload_len:
return None
try:
return json.loads(payload.decode("ascii", errors="ignore"))
except (json.JSONDecodeError, UnicodeDecodeError):
return None
def get_channel_params(head: dict, dev: ScpiDevice,
ch_name: str = "CH2") -> Optional[ChannelParams]:
"""从 HEAD 提取通道参数,并用 SCPI 查询补全实际 offset。"""
for ch in head.get("CHANNEL", []):
if ch.get("NAME", "").upper() == ch_name.upper():
# 通过 SCPI 查询获取实际电压偏移 (比 HEAD OFFSET 更准确)
offset_v = 0.0
try:
offset_text = dev.send_text(f":{ch_name}:OFFSET?")
offset_v = extract_numeric(offset_text) or 0.0
except Exception:
pass
return ChannelParams(
name=ch.get("NAME", ""),
display=ch.get("DISPLAY", "ON").upper() == "ON",
coupling=ch.get("COUPLING", "DC"),
probe=ch.get("PROBE", "1X"),
scale=ch.get("SCALE", "1V"),
offset_head=int(ch.get("OFFSET", 0)),
offset_volts=offset_v,
inverse=ch.get("INVERSE", "OFF").upper() == "ON",
)
return None
# ─── 波形数据采集与解析 ─────────────────────────────────────────
def fetch_waveform_raw(dev: ScpiDevice, channel: int = 2) -> Optional[bytes]:
cmd = f":DATA:WAVE:SCREen:CH{channel}?"
return dev.send(cmd)
def parse_waveform(data: bytes) -> np.ndarray:
"""解析 12-bit 有符号 ADC 波形 (4 字节 LE 长度前缀)。"""
if len(data) < 4:
raise ValueError(f"数据不足 4 字节 (实际 {len(data)})")
payload_len = struct.unpack("<I", data[:4])[0]
payload = data[4:]
if len(payload) != payload_len:
raise ValueError(
f"载荷长度不匹配: 声明 {payload_len} != 实际 {len(payload)}"
)
if len(payload) % 2 != 0:
raise ValueError(f"载荷字节数为奇数: {len(payload)}")
num_points = len(payload) // 2
if num_points == 0:
raise ValueError("空载荷")
raw = np.frombuffer(payload, dtype="<u2", count=num_points) & 0x0FFF
signed = np.where(raw >= 0x0800, raw.astype(np.float64) - _ADC_MAX,
raw.astype(np.float64))
return signed
def adc_to_voltage(adc: np.ndarray, vdiv: float,
offset_volts: float = 0.0) -> np.ndarray:
return adc * (_SCREEN_DIVS_V * vdiv / _ADC_MAX) - offset_volts
# ─── 统计分析 ────────────────────────────────────────────────────
@dataclass
class Ch2Stats:
timestamp: float
datetime: str
min_v: float
max_v: float
pkpk_v: float
avg_v: float
rms_v: float
std_v: float
vtop_v: float
vbase_v: float
vamp_v: float
num_points: int
vdiv: float
offset_v: float
def to_dict(self) -> dict:
return {
"timestamp": self.timestamp,
"datetime": self.datetime,
"min_v": round(self.min_v, 6),
"max_v": round(self.max_v, 6),
"pkpk_v": round(self.pkpk_v, 6),
"avg_v": round(self.avg_v, 6),
"rms_v": round(self.rms_v, 6),
"std_v": round(self.std_v, 6),
"vtop_v": round(self.vtop_v, 6),
"vbase_v": round(self.vbase_v, 6),
"vamp_v": round(self.vamp_v, 6),
"num_points": self.num_points,
"vdiv": self.vdiv,
"offset_v": round(self.offset_v, 6),
}
def compute_histogram_top_base(voltages: np.ndarray,
nbins: int = 100) -> tuple[float, float]:
hist, edges = np.histogram(voltages, bins=nbins)
vmin, vmax = edges[0], edges[-1]
low_thresh = vmin + (vmax - vmin) * 0.1
high_thresh = vmin + (vmax - vmin) * 0.9
mid = (edges[:-1] + edges[1:]) / 2
low_mask = mid < low_thresh
high_mask = mid > high_thresh
if low_mask.any() and high_mask.any():
vbase = float(np.average(mid[low_mask], weights=hist[low_mask] + 1e-12))
vtop = float(np.average(mid[high_mask], weights=hist[high_mask] + 1e-12))
else:
vbase = float(np.min(voltages))
vtop = float(np.max(voltages))
return vtop, vbase
def analyze_waveform(adc: np.ndarray, ch: ChannelParams) -> Ch2Stats:
vdiv = ch.vdiv
offset_v = ch.offset_volts
voltages = adc_to_voltage(adc, vdiv, offset_v)
vtop, vbase = compute_histogram_top_base(voltages)
now = time.time()
return Ch2Stats(
timestamp=now,
datetime=datetime.fromtimestamp(now, tz=timezone.utc).isoformat(),
min_v=float(np.min(voltages)),
max_v=float(np.max(voltages)),
pkpk_v=float(np.max(voltages) - np.min(voltages)),
avg_v=float(np.mean(voltages)),
rms_v=float(np.sqrt(np.mean(np.square(voltages)))),
std_v=float(np.std(voltages, ddof=0)),
vtop_v=vtop,
vbase_v=vbase,
vamp_v=vtop - vbase,
num_points=len(adc),
vdiv=vdiv,
offset_v=offset_v,
)
# ─── 硬件测量模式 ────────────────────────────────────────────────
# 单项测量查询: SCPI 命令后缀 + 响应解析
_SINGLE_MEAS_ITEMS = [
("max_v", "MAX"),
("min_v", "MIN"),
("pkpk_v", "PKPK"),
("vtop_v", "VTOP"),
("vbase_v", "VBASe"),
("vamp_v", "VAMP"),
("avg_v", "AVERage"),
("rms_v", "SQUAresum"),
("cycrms_v", "CYCRms"),
("period", "PERiod"),
("freq", "FREQuency"),
]
def sample_measure_single(dev: ScpiDevice) -> dict:
"""逐项查询 :MEASUrement:CH2:<item>?,返回 dict。"""
result: dict = {}
now = time.time()
result["timestamp"] = now
result["datetime"] = datetime.fromtimestamp(now, tz=timezone.utc).isoformat()
for key, item in _SINGLE_MEAS_ITEMS:
resp = dev.send_text(f":MEASUrement:CH2:{item}?")
cleaned = clean_meas_text(resp)
if cleaned:
try:
result[key] = round(float(cleaned), 6)
except ValueError:
pass
return result
def sample_measure_json(dev: ScpiDevice) -> dict:
"""通过 :MEASUrement:CH2? 一次获取全部测量项 (JSON)。"""
resp = dev.send(":MEASUrement:CH2?")
result: dict = {}
now = time.time()
result["timestamp"] = now
result["datetime"] = datetime.fromtimestamp(now, tz=timezone.utc).isoformat()
if not resp or len(resp) < 4:
return result
payload_len = struct.unpack("<I", resp[:4])[0]
if payload_len + 4 > len(resp):
return result
payload = resp[4:4 + payload_len]
raw_text = payload.decode("ascii", errors="replace")
clean_text = raw_text.replace("\t", "") # 去掉 tab 控制字符
try:
parsed = json.loads(clean_text)
except json.JSONDecodeError:
return result
ch2_data = parsed.get("CH2", {})
# 映射 JSON key → 输出 key
key_map = {
"MAX": "max_v", "MIN": "min_v", "PKPK": "pkpk_v",
"VTOP": "vtop_v", "VBASe": "vbase_v", "VAMP": "vamp_v",
"AVERage": "avg_v", "SQUAresum": "rms_v", "CYCRms": "cycrms_v",
"CURSorrms": "curs_rms_v",
"PERiod": "period", "FREQuency": "freq",
}
for json_key, out_key in key_map.items():
raw_val = ch2_data.get(json_key, "")
# 去掉 "? ,OFF ,ON" 等后缀
clean_val = raw_val.rstrip("?").rstrip(",").rstrip(",OFF").rstrip(",ON").strip()
if clean_val:
num = extract_numeric(clean_val)
if num is not None:
result[out_key] = round(num, 6)
return result
# ─── 采样循环 ────────────────────────────────────────────────────
def _setup_output(path: Optional[str], fieldnames: list[str]):
out_f = None
csv_writer = None
if path:
if path.endswith(".csv"):
out_f = open(path, "w", newline="")
csv_writer = csv.DictWriter(out_f, fieldnames=fieldnames)
csv_writer.writeheader()
else:
out_f = open(path, "w")
return out_f, csv_writer
def _output_record(record: dict, csv_writer, out_f,
csv_fieldnames: Optional[list[str]] = None):
line = json.dumps(record, ensure_ascii=False)
if csv_writer and csv_fieldnames:
row = {k: record.get(k, "") for k in csv_fieldnames}
csv_writer.writerow(row)
out_f.flush()
elif out_f:
out_f.write(line + "\n")
out_f.flush()
else:
print(line)
def _setup_signal_handler() -> list:
running = [True]
def _handler(signum, frame):
running[0] = False
signal.signal(signal.SIGINT, _handler)
signal.signal(signal.SIGTERM, _handler)
return running
def run_measure_mode(dev: ScpiDevice, interval_ms: int,
max_samples: int, output_path: Optional[str]):
"""硬件测量模式 — 逐项查询或 JSON 批量查询。"""
csv_fields = [
"timestamp", "datetime",
"max_v", "min_v", "pkpk_v", "vtop_v", "vbase_v", "vamp_v",
"avg_v", "rms_v", "cycrms_v", "period", "freq",
]
out_f, csv_writer = _setup_output(output_path, csv_fields)
running = _setup_signal_handler()
count = 0
t0 = time.monotonic()
use_json = (len(_SINGLE_MEAS_ITEMS) > 5) # 项多时 JSON 模式更高效
print(f"[INFO] 开始采集 CH2 — 间隔 {interval_ms}ms, 模式 measure"
f"{' (JSON)' if use_json else ' (single)'}",
file=sys.stderr)
while running[0] and (max_samples == 0 or count < max_samples):
cycle_start = time.monotonic()
try:
if use_json:
record = sample_measure_json(dev)
else:
record = sample_measure_single(dev)
except Exception as e:
print(f"[WARN] 第 {count + 1} 次: 测量失败: {e}", file=sys.stderr)
record = None
if record:
count += 1
_output_record(record, csv_writer, out_f, csv_fields)
if count % 10 == 0:
elapsed = time.monotonic() - t0
print(f"[INFO] 已采集 {count} 条 ({elapsed:.1f}s)", file=sys.stderr)
elapsed_since = (time.monotonic() - cycle_start) * 1000
sleep_ms = max(0, interval_ms - elapsed_since)
if sleep_ms > 0 and running[0]:
time.sleep(sleep_ms / 1000.0)
elapsed_total = time.monotonic() - t0
print(f"[INFO] 采集结束 — 共 {count} 条, 耗时 {elapsed_total:.1f}s, "
f"实际频率 {count/elapsed_total:.1f} Hz" if elapsed_total > 0 else "",
file=sys.stderr)
if out_f:
out_f.close()
def run_waveform_mode(dev: ScpiDevice, interval_ms: int,
max_samples: int, output_path: Optional[str]):
"""数据接口模式 — 强制触发 + HEAD + CH2 波形,软件计算。
注意: NDS202E 在 RUN 模式下 :DATA:WAVE 返回的是冻结数据。
需要通过 :TRIGger:SINGLE 强制触发新采集后再读数据。
"""
head = fetch_head(dev)
if head is None:
print("[FATAL] 无法获取 HEAD 信息", file=sys.stderr)
return
ch2 = get_channel_params(head, dev)
if ch2 is None:
print("[FATAL] HEAD 中未找到 CH2 通道", file=sys.stderr)
return
csv_fields = [
"timestamp", "datetime",
"min_v", "max_v", "pkpk_v", "avg_v", "rms_v", "std_v",
"vtop_v", "vbase_v", "vamp_v",
"num_points", "vdiv", "offset_v",
]
out_f, csv_writer = _setup_output(output_path, csv_fields)
running = _setup_signal_handler()
count = 0
t0 = time.monotonic()
# 确保示波器在 RUN 模式
dev.write_cmd(":RUNning RUN")
print(f"[INFO] 开始采集 CH2 — 间隔 {interval_ms}ms, 模式 waveform"
f" (TRIG:SINGLE), 档位 {ch2.scale}, 探头 {ch2.probe}",
file=sys.stderr)
while running[0] and (max_samples == 0 or count < max_samples):
cycle_start = time.monotonic()
try:
# 1. 强制单次触发采集新波形
dev.write_cmd(":TRIGger:SINGLE")
# :TRIGger:SINGLE 完成采集后示波器自动 STOP,等待固定时间
# (依赖信号存在触发条件;若无触发则等待超时)
time.sleep(1.5)
# 2. 读取波形数据
raw = fetch_waveform_raw(dev, channel=2)
if raw is None or len(raw) < 6:
print(f"[WARN] 第 {count + 1} 次: 波形数据为空", file=sys.stderr)
record = None
else:
adc = parse_waveform(raw)
stats = analyze_waveform(adc, ch2)
record = stats.to_dict()
# 3. 恢复 RUN
dev.write_cmd(":RUNning RUN")
except Exception as e:
print(f"[WARN] 第 {count + 1} 次: 失败: {e}", file=sys.stderr)
record = None
if record:
count += 1
_output_record(record, csv_writer, out_f, csv_fields)
if count % 10 == 0:
elapsed = time.monotonic() - t0
print(f"[INFO] 已采集 {count} 条 ({elapsed:.1f}s)", file=sys.stderr)
elapsed_since = (time.monotonic() - cycle_start) * 1000
sleep_ms = max(0, interval_ms - elapsed_since)
if sleep_ms > 0 and running[0]:
time.sleep(sleep_ms / 1000.0)
elapsed_total = time.monotonic() - t0
print(f"[INFO] 采集结束 — 共 {count} 条, 耗时 {elapsed_total:.1f}s",
file=sys.stderr)
dev.write_cmd(":RUNning RUN")
if out_f:
out_f.close()
# ─── 入口 ────────────────────────────────────────────────────────
def main():
parser = argparse.ArgumentParser(
description="CH2 通道实时数据采集记录器 (原生 PyUSB + SCPI, NDS202E/NDS102U)",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
示例:
python ch2_recorder.py # 500ms 间隔,stdout (JSON)
python ch2_recorder.py -i 200 -o ch2.csv # 200ms 间隔,CSV 文件
python ch2_recorder.py -i 100 -n 1000 # 100ms 间隔,采集 1000 次
python ch2_recorder.py --mode measure -o m.csv # 硬件测量模式 (实时,推荐)
python ch2_recorder.py --mode waveform # 数据接口 + TRIG:SINGLE
""",
)
parser.add_argument(
"-i", "--interval", type=int, default=_DEFAULT_INTERVAL_MS,
help=f"采样间隔 (毫秒),默认 {_DEFAULT_INTERVAL_MS}",
)
parser.add_argument(
"-n", "--count", type=int, default=0,
help="最大采样次数,0 表示不限(Ctrl-C 停止)",
)
parser.add_argument(
"-o", "--output", type=str, default=None,
help="输出文件路径 (.csv 或 .jsonl),默认 stdout (JSON 每行一条)",
)
parser.add_argument(
"--mode", type=str, choices=("measure", "waveform"),
default="measure",
help="采样模式: measure=硬件测量接口(实时,推荐), waveform=数据接口+软件计算 (默认 measure)",
)
parser.add_argument(
"--vid", type=str, default=None,
help=f"USB Vendor ID (十六进制),默认 0x{DEFAULT_VID:04X}",
)
parser.add_argument(
"--pid", type=str, default=None,
help=f"USB Product ID (十六进制),默认 0x{DEFAULT_PID:04X}",
)
parser.add_argument(
"--json-mode", action="store_true", default=True,
help="measure 模式下使用 :MEASUrement:CH2? JSON 批量获取 (更快,默认)",
)
parser.add_argument(
"--single-mode", action="store_true", default=False,
help="measure 模式下使用逐项 :MEASUrement:CH2:<item>? 查询",
)
args = parser.parse_args()
vid = int(args.vid, 16) if args.vid else DEFAULT_VID
pid = int(args.pid, 16) if args.pid else DEFAULT_PID
if args.interval < 10:
print("[WARN] 采样间隔过小 (< 10ms)", file=sys.stderr)
print(f"[INFO] 连接 USB 设备 (VID=0x{vid:04X}, PID=0x{pid:04X})...",
file=sys.stderr)
try:
with ScpiDevice(vid, pid) as dev:
idn = dev.idn()
print(f"[INFO] 设备: {idn}", file=sys.stderr)
if args.mode == "waveform":
run_waveform_mode(dev, args.interval, args.count, args.output)
else:
# measure 模式
if args.single_mode:
global _SINGLE_MEAS_ITEMS
_SINGLE_MEAS_ITEMS = _SINGLE_MEAS_ITEMS[:5] # 逐项时只取核心项
run_measure_mode(dev, args.interval, args.count, args.output)
except RuntimeError as e:
print(f"[FATAL] {e}", file=sys.stderr)
sys.exit(1)
except KeyboardInterrupt:
print("\n[INFO] 用户中断", file=sys.stderr)
finally:
print("[INFO] 退出", file=sys.stderr)
if __name__ == "__main__":
main()

82
backend/tools/check_data.py 普通文件
查看文件

@ -0,0 +1,82 @@
#!/usr/bin/env python3
"""绕过封装 + 尝试多种方式强制刷新采集后再读。"""
import hashlib, sys, os, time
import usb.core, usb.util
VID, PID = 0x5345, 0x1234
dev = usb.core.find(idVendor=VID, idProduct=PID)
assert dev, "设备未找到"
for cfg in dev:
for intf in cfg:
if dev.is_kernel_driver_active(intf.bInterfaceNumber):
dev.detach_kernel_driver(intf.bInterfaceNumber)
dev.set_configuration()
intf = dev.get_active_configuration()[(0, 0)]
ep_out = ep_in = None
for ep in intf:
d = usb.util.endpoint_direction(ep.bEndpointAddress)
if d == usb.util.ENDPOINT_OUT: ep_out = ep
elif d == usb.util.ENDPOINT_IN: ep_in = ep
assert ep_out and ep_in
MAXPKT = ep_in.wMaxPacketSize
def send(cmd: bytes, timeout=5000) -> bytes:
dev.write(ep_out, cmd, timeout=timeout)
resp = b''
while True:
try:
data = dev.read(ep_in, MAXPKT, timeout=timeout)
if not data: break
resp += data.tobytes()
if len(data) < MAXPKT: break
except usb.core.USBError as e:
if e.errno == 110: break
raise
return resp
def m5(d): return hashlib.md5(d).hexdigest()[:8] if d else "None"
# ── 初始状态 ──
idn = send(b'*IDN?\n').decode('ascii','ignore').strip()
print(f"设备: {idn}")
print(f"max_pkt={MAXPKT}")
# ── 初读(当前冻结数据) ──
ch1 = send(b":DATA:WAVE:SCREen:CH1?\n")
_init_md5 = m5(ch1)
print(f"\n[初始] CH1={len(ch1)}B md5={_init_md5}")
# ── 测试 1: STOP + RUN 再读 ──
print("\n--- 测试1: STOP->RUN ---")
send(b":RUNning STOP\n")
time.sleep(0.5)
send(b":RUNning RUN\n")
time.sleep(1.0)
ch1 = send(b":DATA:WAVE:SCREen:CH1?\n")
print(f"CH1={len(ch1)}B md5={m5(ch1)} 变化={'YES' if m5(ch1) != _init_md5 else 'NO'}")
# ── 测试 2: TRIGger:SINGLE 再读 ──
print("\n--- 测试2: TRIG:SINGLE ---")
for i in range(3):
send(b":TRIGger:SINGLE\n")
time.sleep(1.0)
ch1 = send(b":DATA:WAVE:SCREen:CH1?\n")
print(f" [{i+1}] CH1={len(ch1)}B md5={m5(ch1)} "
f"变化={'YES' if m5(ch1) != _init_md5 else 'NO'}")
# ── 测试 3: AUTOset 再读 ──
print("\n--- 测试3: AUTOset ---")
send(b":AUTOset ON\n")
time.sleep(2.0)
ch1 = send(b":DATA:WAVE:SCREen:CH1?\n")
print(f"CH1={len(ch1)}B md5={m5(ch1)} 变化={'YES' if m5(ch1) != _init_md5 else 'NO'}")
# ── 测试 4: 读 measurement 值看是否变化 ──
print("\n--- 测试4: MEASurement (对比) ---")
for i in range(5):
r = send(b":MEASUrement:CH1:PKPK?\n")
print(f" [{i+1}] CH1_PKPK={r.decode('ascii','ignore').strip()}")
print("\nDone")
usb.util.dispose_resources(dev)

查看文件

@ -0,0 +1,398 @@
"""
示波器数据层 — 可复用的 USB SCPI 通信与数据解析模块
提供 OscilloscopeData 类用于连接、获取 BMP/HEAD/波形,以及独立的数据解析函数。
"""
from __future__ import annotations
import io
import json
import os
import re
import struct
import sys
import threading
import time
from dataclasses import dataclass, field
from typing import Optional
import numpy as np
from PIL import Image
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from app.hardware.oscilloscope import Oscilloscope
# ─── 常量 ────────────────────────────────────────────────────────
_SCALE_RE = re.compile(r"([\d.]+)\s*([numk]?[sv])\s*", re.IGNORECASE)
_UNIT_MULTIPLIERS: dict[str, float] = {
"nv": 1e-9, "uv": 1e-6, "mv": 1e-3, "v": 1.0, "kv": 1e3,
"ns": 1e-9, "us": 1e-6, "ms": 1e-3, "s": 1.0, "ks": 1e3,
}
_SCREEN_DIVS_H = 10 # 水平分度数
_SCREEN_DIVS_V = 8 # 垂直分度数
_ADC_MAX = 0x1000 # 12-bit = 4096
# ─── 数据结构 ────────────────────────────────────────────────────
@dataclass
class ChannelInfo:
name: str = ""
display: bool = True
coupling: str = "dc"
probe: str = "1x"
scale: str = "1v"
offset: int = 0
inverse: bool = False
@property
def vdiv(self) -> float:
"""电压档位 (V/div),已考虑探头比例。"""
return parse_scale_str(self.scale)
@property
def probe_ratio(self) -> float:
return parse_probe_ratio(self.probe)
@property
def offset_volts(self) -> float:
"""垂直偏移电压 (V)。offset 单位为 0.01 格。"""
return self.offset / 100.0 * self.vdiv
@dataclass
class TimebaseInfo:
scale: str = "1.0ms"
hoffset: int = 0
@property
def scale_sec(self) -> float:
return parse_timebase(self.scale)
@dataclass
class SampleInfo:
fullscreen: int = 1520
datalen: int = 1520
samplerate: str = "500ks/s"
type: str = "sample"
depmem: str = "10k"
@dataclass
class HeadInfo:
timebase: TimebaseInfo = field(default_factory=TimebaseInfo)
sample: SampleInfo = field(default_factory=SampleInfo)
channels: list[ChannelInfo] = field(default_factory=list)
datatype: str = "screen"
runstatus: str = "auto"
def get_channel(self, name: str) -> Optional[ChannelInfo]:
for ch in self.channels:
if ch.name == name:
return ch
return None
@dataclass
class WaveformSnapshot:
"""一次完整的数据快照。"""
idn: Optional[str] = None
bmp_img: Optional[Image.Image] = None
head: Optional[HeadInfo] = None
ch1_adc: Optional[np.ndarray] = None
ch2_adc: Optional[np.ndarray] = None
# ─── 单位字符串解析 ──────────────────────────────────────────────
def parse_scale_str(raw: str) -> float:
"""解析电压档位字符串,如 '5.00mv' → 0.005, '1v' → 1.0。"""
m = _SCALE_RE.search(raw.lower().strip())
if m:
return float(m.group(1)) * _UNIT_MULTIPLIERS.get(m.group(2), 1.0)
try:
return float(raw)
except (ValueError, TypeError):
return 1.0
def parse_timebase(raw: str) -> float:
"""解析时基字符串,如 '1.0ms' → 0.001, '500us' → 0.0005。"""
return parse_scale_str(raw)
def parse_probe_ratio(raw: str) -> float:
"""解析探头比例,如 '10x' → 10.0, '1x' → 1.0。"""
try:
return float(raw.strip().lower().rstrip("x"))
except (ValueError, TypeError):
return 1.0
# ─── 数据包解析 ──────────────────────────────────────────────────
def _strip_length_header(data: bytes) -> bytes:
"""去除 4 字节小端长度前缀,返回纯载荷。
若声明长度与实不一致,说明 USB 响应串扰,抛出异常由调用方丢弃。
"""
if len(data) < 4:
raise ValueError(f"响应不足 4 字节 (实际 {len(data)})")
payload_len = struct.unpack("<I", data[:4])[0]
payload = data[4:]
if len(payload) != payload_len:
raise ValueError(
f"声明长度 {payload_len} != 实际 {len(payload)},丢弃脏数据")
return payload
def _parse_waveform_raw(payload: bytes) -> np.ndarray:
"""从纯二进制载荷解析 12-bit 有符号波形数据。"""
num_points = len(payload) // 2
if num_points == 0:
raise ValueError("空载荷")
raw = np.frombuffer(payload, dtype="<u2", count=num_points) & 0x0FFF
signed = np.where(raw >= 0x0800, raw.astype(np.float64) - _ADC_MAX,
raw.astype(np.float64))
return signed
def parse_waveform(data: bytes) -> np.ndarray:
"""解析 CH<x> 波形数据。
尝试两种格式,自动选择成功的:
1) 4 字节长度前缀 + 12-bit 数据(SCPI 规范)
2) 纯 12-bit 数据无前缀(某些固件版本)
奇数长度时丢弃末尾 1 字节。
"""
_N = len(data)
# 格式 1:4 字节前缀
if _N >= 4:
hdr = struct.unpack("<I", data[:4])[0]
payload = data[4:]
if len(payload) == hdr and len(payload) % 2 == 0:
return _parse_waveform_raw(payload)
# 格式 2:无前缀,整个响应即数据
usable = _N if _N % 2 == 0 else _N - 1
if usable >= 4:
return _parse_waveform_raw(data[:usable])
raise ValueError(f"无法解析波形数据: {_N} bytes")
def parse_bmp(data: bytes) -> bytes:
"""解析 BMP 响应,返回纯 BMP 字节流。"""
return _strip_length_header(data)
def _get_key(obj: dict, *keys: str, default=None):
"""兼容大小写 key: 先查原始 key,再查 .upper() 和 .lower()。"""
for k in keys:
if k in obj:
return obj[k]
ku = k.upper()
if ku in obj:
return obj[ku]
kl = k.lower()
if kl in obj:
return obj[kl]
return default
def parse_head(data: bytes) -> HeadInfo:
"""解析 HEAD JSON 响应,返回 HeadInfo 对象。
兼容 OWON NDS102U (小写 key) 和 NDS202E (全大写 key) 固件版本。
格式: 4 字节长度前缀 + JSON 文本(与 BMP / 波形一致,DATA 子系统统一)。"""
payload = _strip_length_header(data)
text = payload.decode("ascii", errors="ignore").strip()
raw = json.loads(text)
tb = _get_key(raw, "timebase", default={})
timebase = TimebaseInfo(
scale=_get_key(tb, "scale", default="1.0ms"),
hoffset=_get_key(tb, "hoffset", default=0),
)
sp = _get_key(raw, "sample", default={})
sample = SampleInfo(
fullscreen=_get_key(sp, "fullscreen", default=1520),
datalen=_get_key(sp, "datalen", default=1520),
samplerate=_get_key(sp, "samplerate", default="500ks/s"),
type=_get_key(sp, "type", default="sample"),
depmem=_get_key(sp, "depmem", default="10k"),
)
channels = []
ch_list = _get_key(raw, "channel", default=[])
for ch in ch_list:
display_raw = _get_key(ch, "display", default="on")
inverse_raw = _get_key(ch, "inverse", default="off")
channels.append(ChannelInfo(
name=_get_key(ch, "name", default=""),
display=str(display_raw).lower() == "on",
coupling=_get_key(ch, "coupling", default="dc"),
probe=_get_key(ch, "probe", default="1x"),
scale=_get_key(ch, "scale", default="1v"),
offset=_get_key(ch, "offset", default=0),
inverse=str(inverse_raw).lower() == "on",
))
return HeadInfo(
timebase=timebase,
sample=sample,
channels=channels,
datatype=_get_key(raw, "datatype", default="screen"),
runstatus=_get_key(raw, "runstatus", default="auto"),
)
# ─── 电压与时间轴 ────────────────────────────────────────────────
def adc_to_voltage(adc: np.ndarray, vdiv: float,
offset_volts: float = 0.0) -> np.ndarray:
"""有符号 12-bit ADC 值转为电压 (V)。
adc: 范围 [-2048, 2047] 的 float64 数组
vdiv: 垂直档位 V/div
offset_volts: 垂直偏移电压 (V)
"""
return adc * (_SCREEN_DIVS_V * vdiv / _ADC_MAX) - offset_volts
def build_time_axis(num_points: int, tb_scale_sec: float) -> np.ndarray:
"""根据数据点数和时基构建时间轴 (s)。"""
if num_points <= 0:
return np.array([])
return np.arange(num_points) * (_SCREEN_DIVS_H * tb_scale_sec / num_points)
# ─── 示波器数据获取器 ────────────────────────────────────────────
class OscilloscopeData:
"""OWON NDS102U 示波器 USB SCPI 数据获取封装。
用法:
with OscilloscopeData() as od:
snap = od.snapshot() # 完整快照 (BMP + HEAD + CH1 + CH2)
bmp_img = od.fetch_bmp() # 仅 BMP
head = od.fetch_head() # 仅 HEAD
ch1 = od.fetch_waveform(1) # 仅 CH1
"""
def __init__(self, vid: int = 0x5345, pid: int = 0x1234):
self._osc = Oscilloscope(vid, pid)
self._connected = False
self._lock = threading.Lock()
# ── 连接管理 ──
def connect(self):
self._osc.connect()
self._connected = True
def disconnect(self):
if self._connected:
self._osc.disconnect()
self._connected = False
def __enter__(self):
self.connect()
return self
def __exit__(self, *args):
self.disconnect()
@property
def is_connected(self) -> bool:
return self._connected
# ── 原始命令(线程安全) ──
def _cmd(self, scpi: str, timeout: int = 5000) -> Optional[bytes]:
with self._lock:
return self._osc.send_command(scpi, timeout=timeout)
# ── 高层获取方法 ──
def fetch_idn(self) -> Optional[str]:
resp = self._cmd("*IDN?")
if resp:
return resp.decode("ascii", errors="ignore").strip()
return None
def fetch_bmp(self, timeout: int = 15000) -> Optional[Image.Image]:
resp = self._cmd(":DATA:WAVE:SCREen:BMP?", timeout=timeout)
if resp is None:
return None
try:
bmp_bytes = parse_bmp(resp)
return Image.open(io.BytesIO(bmp_bytes))
except Exception as e:
print(f" BMP 解析失败: {e}")
return None
def fetch_head(self) -> Optional[HeadInfo]:
resp = self._cmd(":DATA:WAVE:SCREen:HEAD?")
if resp is None:
return None
try:
return parse_head(resp)
except (json.JSONDecodeError, Exception) as e:
print(f" HEAD 解析失败: {e}")
return None
def fetch_waveform(self, channel: int) -> Optional[np.ndarray]:
"""获取指定通道波形数据。channel: 1 或 2。"""
cmd = f":DATA:WAVE:SCREen:CH{channel}?"
resp = self._cmd(cmd)
if resp is None:
return None
try:
return parse_waveform(resp)
except Exception as e:
print(f" CH{channel} 解析失败: {e}")
return None
def snapshot_light(self) -> WaveformSnapshot:
"""轻量快照 (HEAD + CH1 + CH2),不含 BMP。用于实时刷新。"""
snap = WaveformSnapshot()
snap.head = self.fetch_head()
if snap.head:
snap.ch1_adc = self.fetch_waveform(1)
snap.ch2_adc = self.fetch_waveform(2)
return snap
def snapshot(self) -> WaveformSnapshot:
"""完整快照 (IDN + BMP + HEAD + CH1 + CH2)。"""
snap = WaveformSnapshot()
snap.idn = self.fetch_idn()
if snap.idn:
print(f" 设备: {snap.idn}")
snap.bmp_img = self.fetch_bmp()
if snap.bmp_img:
print(f" BMP: {snap.bmp_img.size[0]}x{snap.bmp_img.size[1]}")
snap.head = self.fetch_head()
if snap.head:
for ch in snap.head.channels:
print(f" {ch.name}: {ch.scale} ({ch.probe}), offset={ch.offset}")
print(f" 时基: {snap.head.timebase.scale}, 点数: {snap.head.sample.datalen}")
snap.ch1_adc = self.fetch_waveform(1)
if snap.ch1_adc is not None:
print(f" CH1: {len(snap.ch1_adc)} 点")
snap.ch2_adc = self.fetch_waveform(2)
if snap.ch2_adc is not None:
print(f" CH2: {len(snap.ch2_adc)} 点")
return snap

查看文件

@ -0,0 +1,419 @@
#!/usr/bin/env python3
"""
示波器屏幕截图与波形渲染工具 (PyQtGraph 版)
依赖 oscilloscope_data.py 提供数据层,本模块专注 PyQtGraph 渲染。
用法:
python oscilloscope_viewer.py # 单次快照 (BMP + 时域 + XY)
python oscilloscope_viewer.py snapshot # 同上
python oscilloscope_viewer.py live # 连续实时波形 (时域 + XY)
python oscilloscope_viewer.py live --interval 300
"""
from __future__ import annotations
import io
import queue
import sys
import threading
import time
from typing import Optional
import numpy as np
from PIL import Image
from PyQt5 import QtWidgets, QtCore, QtGui
import pyqtgraph as pg
from oscilloscope_data import (
OscilloscopeData,
WaveformSnapshot,
HeadInfo,
adc_to_voltage,
build_time_axis,
)
# ─── 常量 ────────────────────────────────────────────────────────
CH_COLORS = {"CH1": (255, 179, 71), "CH2": (119, 221, 119)} # RGB
XY_COLOR = (100, 149, 237)
BG_COLOR = "#1e1e1e"
GRID_COLOR = "#444444"
_SCREEN_DIVS = 10
def _pil_to_qpixmap(pil_img: Image.Image) -> QtGui.QPixmap:
"""PIL Image → QPixmap,绕过 Pillow 12.x 的 ImageQt 兼容性问题。"""
buf = io.BytesIO()
pil_img.save(buf, format="BMP")
pix = QtGui.QPixmap()
pix.loadFromData(buf.getvalue())
return pix
def _channel_params(head: Optional[HeadInfo]) -> dict:
ch1_vdiv, ch1_off = 1.0, 0.0
ch2_vdiv, ch2_off = 1.0, 0.0
tb_scale = 0.001
if head:
for ch in head.channels:
if ch.name == "ch1":
ch1_vdiv, ch1_off = ch.vdiv, ch.offset_volts
elif ch.name == "ch2":
ch2_vdiv, ch2_off = ch.vdiv, ch.offset_volts
tb_scale = head.timebase.scale_sec
return dict(ch1_vdiv=ch1_vdiv, ch1_off=ch1_off,
ch2_vdiv=ch2_vdiv, ch2_off=ch2_off,
tb_scale=tb_scale)
# ─── QApplication 单例 ───────────────────────────────────────────
_app: Optional[QtWidgets.QApplication] = None
def _get_app() -> QtWidgets.QApplication:
global _app
if _app is None:
_app = QtWidgets.QApplication(sys.argv)
return _app
# ─── 快照窗口 ────────────────────────────────────────────────────
class SnapshotWindow(QtWidgets.QMainWindow):
"""单次快照:BMP 截图 + 时域波形 + XY 模式。"""
def __init__(self, snap: WaveformSnapshot):
super().__init__()
self.snap = snap
self.params = _channel_params(snap.head)
self._setup()
def _setup(self):
self.setWindowTitle("示波器 — 快照 — OWON NDS102U")
self.resize(1400, 900)
cw = QtWidgets.QWidget()
self.setCentralWidget(cw)
layout = QtWidgets.QGridLayout(cw)
layout.setSpacing(6)
has_bmp = self.snap.bmp_img is not None
has_wave = self.snap.ch1_adc is not None or self.snap.ch2_adc is not None
row = 0
# BMP
if has_bmp:
pix = _pil_to_qpixmap(self.snap.bmp_img)
lbl = QtWidgets.QLabel()
lbl.setPixmap(pix)
lbl.setAlignment(QtCore.Qt.AlignCenter)
gb = QtWidgets.QGroupBox("屏幕截图")
gb_layout = QtWidgets.QVBoxLayout(gb)
gb_layout.addWidget(lbl)
layout.addWidget(gb, row, 0)
row += 1
# 时域 + XY
if has_wave:
pw_time = self._make_time_plot()
pw_xy = self._make_xy_plot()
layout.addWidget(pw_time, 0, 1, max(row, 1), 1)
layout.addWidget(pw_xy, row, 0 if not has_bmp else 0, 1, 1)
# 信息
info_text = self._info_text()
info_lbl = QtWidgets.QLabel(info_text)
info_lbl.setStyleSheet("background:#fffef0;padding:8px;font-family:monospace;")
layout.addWidget(info_lbl, row, 1, 1, 1)
def _make_time_plot(self):
pw = pg.PlotWidget(title="时域波形")
pw.setBackground(BG_COLOR)
pw.showGrid(x=True, y=True, alpha=0.3)
pw.setLabel("bottom", "时间", units="s")
pw.setLabel("left", "电压", units="V")
pw.addLegend()
tb = self.params["tb_scale"]
for adc, vdiv, off, label, color in [
(self.snap.ch1_adc, self.params["ch1_vdiv"],
self.params["ch1_off"], "CH1", CH_COLORS["CH1"]),
(self.snap.ch2_adc, self.params["ch2_vdiv"],
self.params["ch2_off"], "CH2", CH_COLORS["CH2"]),
]:
if adc is not None and len(adc) > 0:
t = build_time_axis(len(adc), tb)
v = adc_to_voltage(adc, vdiv, off)
pen = pg.mkPen(color=color, width=1.2)
pw.plot(t, v, pen=pen, name=label)
return pw
def _make_xy_plot(self):
pw = pg.PlotWidget(title="XY 模式 (李萨如图)")
pw.setBackground(BG_COLOR)
pw.showGrid(x=True, y=True, alpha=0.3)
pw.setLabel("bottom", "CH1", units="V")
pw.setLabel("left", "CH2", units="V")
pw.setAspectLocked(True)
ch1, ch2 = self.snap.ch1_adc, self.snap.ch2_adc
if ch1 is not None and ch2 is not None:
n = min(len(ch1), len(ch2))
if n > 1:
v1 = adc_to_voltage(ch1[:n], self.params["ch1_vdiv"],
self.params["ch1_off"])
v2 = adc_to_voltage(ch2[:n], self.params["ch2_vdiv"],
self.params["ch2_off"])
pen = pg.mkPen(color=XY_COLOR, width=1.0)
pw.plot(v1, v2, pen=pen)
return pw
def _info_text(self) -> str:
p = self.params
lines = [
f"设备: {self.snap.idn or 'N/A'}",
f"CH1: {p['ch1_vdiv'] * 1e3:.1f}mV/div",
f"CH2: {p['ch2_vdiv'] * 1e3:.1f}mV/div",
f"时基: {p['tb_scale'] * 1e3:.3g}ms/div",
]
if self.snap.ch1_adc is not None:
lines.append(f"CH1: {len(self.snap.ch1_adc)} 点")
if self.snap.ch2_adc is not None:
lines.append(f"CH2: {len(self.snap.ch2_adc)} 点")
return "\n".join(lines)
# ─── 实时窗口 ────────────────────────────────────────────────────
class LiveWindow(QtWidgets.QMainWindow):
"""连续实时波形:后台线程取 USB → QTimer 定时刷新曲线。"""
def __init__(self, interval_ms: int = 300):
super().__init__()
self.interval_ms = interval_ms
self.dev: Optional[OscilloscopeData] = None
self.params: dict = {}
self._frame_count = 0
# 队列与线程
self._data_queue: queue.Queue = queue.Queue(maxsize=1)
self._stop_event = threading.Event()
self._fetch_thread: Optional[threading.Thread] = None
# 曲线引用
self._curve1: Optional[pg.PlotDataItem] = None
self._curve2: Optional[pg.PlotDataItem] = None
self._curve_xy: Optional[pg.PlotDataItem] = None
self._setup_ui()
# ── UI ───────────────────────────────────────────────────
def _setup_ui(self):
self.setWindowTitle("示波器 — 实时波形 — OWON NDS102U")
self.resize(1400, 650)
cw = QtWidgets.QWidget()
self.setCentralWidget(cw)
hbox = QtWidgets.QHBoxLayout(cw)
# 时域
self._pw_time = pg.PlotWidget(title="时域波形")
self._pw_time.setBackground(BG_COLOR)
self._pw_time.showGrid(x=True, y=True, alpha=0.3)
self._pw_time.setLabel("bottom", "时间", units="s")
self._pw_time.setLabel("left", "电压", units="V")
self._pw_time.addLegend()
pen1 = pg.mkPen(color=CH_COLORS["CH1"], width=1.2)
pen2 = pg.mkPen(color=CH_COLORS["CH2"], width=1.2)
self._curve1 = self._pw_time.plot([], [], pen=pen1, name="CH1")
self._curve2 = self._pw_time.plot([], [], pen=pen2, name="CH2")
hbox.addWidget(self._pw_time)
# XY
self._pw_xy = pg.PlotWidget(title="XY 模式 (李萨如图)")
self._pw_xy.setBackground(BG_COLOR)
self._pw_xy.showGrid(x=True, y=True, alpha=0.3)
self._pw_xy.setLabel("bottom", "CH1", units="V")
self._pw_xy.setLabel("left", "CH2", units="V")
self._pw_xy.setAspectLocked(True)
pen_xy = pg.mkPen(color=XY_COLOR, width=1.0)
self._curve_xy = self._pw_xy.plot([], [], pen=pen_xy)
hbox.addWidget(self._pw_xy)
# 状态栏
self.statusBar().showMessage("就绪")
# 定时器
self._timer = QtCore.QTimer()
self._timer.timeout.connect(self._on_timer)
self._timer.start(self.interval_ms)
# ── 启动 ─────────────────────────────────────────────────
def start(self):
print("[实时模式] 正在连接示波器...")
self.dev = OscilloscopeData()
try:
self.dev.connect()
except RuntimeError as e:
print(f"连接失败: {e}")
return
print("已连接,关闭窗口退出")
head = self.dev.fetch_head()
self.params = _channel_params(head)
# 初始 X 轴范围
if self._curve1 is not None:
self._pw_time.setXRange(0, _SCREEN_DIVS * self.params["tb_scale"])
# 后台取数线程
self._fetch_thread = threading.Thread(target=self._fetch_loop, daemon=True)
self._fetch_thread.start()
# ── 后台线程 ─────────────────────────────────────────────
def _fetch_loop(self):
while not self._stop_event.is_set():
try:
ch1 = self.dev.fetch_waveform(1) # type: ignore[union-attr]
time.sleep(0.05)
ch2 = self.dev.fetch_waveform(2) # type: ignore[union-attr]
self.dev._cmd(":RUNning RUN") # type: ignore[union-attr]
except Exception:
time.sleep(0.1)
continue
# 只保留最新一帧
while not self._data_queue.empty():
try:
self._data_queue.get_nowait()
except queue.Empty:
break
try:
self._data_queue.put_nowait((ch1, ch2))
except queue.Full:
pass
# ── 定时回调 (主线程) ────────────────────────────────────
def _on_timer(self):
try:
ch1_adc, ch2_adc = self._data_queue.get_nowait()
except queue.Empty:
return # 无新数据,跳过
self._frame_count += 1
self.statusBar().showMessage(
f"帧 #{self._frame_count} ({self.interval_ms}ms 刷新)")
tb = self.params["tb_scale"]
n1 = len(ch1_adc) if ch1_adc is not None else 0
n2 = len(ch2_adc) if ch2_adc is not None else 0
if self._frame_count % 20 == 1:
print(f" [#{self._frame_count}] CH1={n1}pts CH2={n2}pts tb={tb*1e3:.2f}ms")
try:
self._apply_data(ch1_adc, ch2_adc, tb)
except Exception as e:
print(f" [UI 错误] {e}")
# ── 数据应用到曲线 ───────────────────────────────────────
def _apply_data(self, ch1_adc, ch2_adc, tb: float):
# 时域
if ch1_adc is not None and len(ch1_adc) > 0:
t = build_time_axis(len(ch1_adc), tb)
v = adc_to_voltage(ch1_adc, self.params["ch1_vdiv"],
self.params["ch1_off"])
self._curve1.setData(t, v)
if ch2_adc is not None and len(ch2_adc) > 0:
t = build_time_axis(len(ch2_adc), tb)
v = adc_to_voltage(ch2_adc, self.params["ch2_vdiv"],
self.params["ch2_off"])
self._curve2.setData(t, v)
# XY
if (ch1_adc is not None and ch2_adc is not None
and len(ch1_adc) > 1 and len(ch2_adc) > 1):
n = min(len(ch1_adc), len(ch2_adc))
v1 = adc_to_voltage(ch1_adc[:n], self.params["ch1_vdiv"],
self.params["ch1_off"])
v2 = adc_to_voltage(ch2_adc[:n], self.params["ch2_vdiv"],
self.params["ch2_off"])
self._curve_xy.setData(v1, v2)
self._pw_time.autoRange()
self._pw_xy.autoRange()
if self._frame_count % 20 == 1:
if ch1_adc is not None and len(ch1_adc) > 10:
import hashlib
h = hashlib.md5(ch1_adc.tobytes()).hexdigest()[:8]
print(f" [#{self._frame_count}] CH1[0:3]={ch1_adc[:3].tolist()}"
f" ch1_md5={h}")
# ── 关闭 ─────────────────────────────────────────────────
def closeEvent(self, event):
self._stop_event.set()
self._timer.stop()
if self._fetch_thread is not None:
self._fetch_thread.join(timeout=2.0)
if self.dev:
self.dev.disconnect()
self.dev = None
print(f"已断开,共 {self._frame_count} 帧")
event.accept()
# ─── 入口 ────────────────────────────────────────────────────────
def snapshot_view():
"""单次快照。"""
print("[快照模式] 正在连接示波器...")
try:
with OscilloscopeData() as dev:
snap = dev.snapshot()
except RuntimeError as e:
print(f"连接失败: {e}")
sys.exit(1)
app = _get_app()
win = SnapshotWindow(snap)
win.show()
app.exec_()
def live_view(interval_ms: int = 300):
"""连续实时波形。"""
app = _get_app()
win = LiveWindow(interval_ms)
win.show()
win.start()
app.exec_()
def main():
import argparse
parser = argparse.ArgumentParser(description="示波器截图与波形观测工具")
sub = parser.add_subparsers(dest="mode")
sub.add_parser("snapshot", help="单次快照 (默认)")
live_parser = sub.add_parser("live", help="连续实时波形")
live_parser.add_argument("--interval", type=int, default=300,
help="刷新间隔 (毫秒), 默认 300")
args = parser.parse_args()
if args.mode == "live":
live_view(interval_ms=args.interval)
else:
snapshot_view()
if __name__ == "__main__":
main()

91
backend/tools/scpi_repl.py 普通文件
查看文件

@ -0,0 +1,91 @@
#!/usr/bin/env python3
"""SCPI REPL — 直接输入 SCPI 命令看设备回复。"""
import sys, os, binascii
import usb.core, usb.util
VID, PID = 0x5345, 0x1234
dev = usb.core.find(idVendor=VID, idProduct=PID)
assert dev, "设备未找到: 请确认 USB 已连且 kernel driver 未占用"
for cfg in dev:
for intf in cfg:
if dev.is_kernel_driver_active(intf.bInterfaceNumber):
dev.detach_kernel_driver(intf.bInterfaceNumber)
dev.set_configuration()
intf = dev.get_active_configuration()[(0, 0)]
ep_out = ep_in = None
for ep in intf:
d = usb.util.endpoint_direction(ep.bEndpointAddress)
if d == usb.util.ENDPOINT_OUT: ep_out = ep
elif d == usb.util.ENDPOINT_IN: ep_in = ep
assert ep_out and ep_in
MAXPKT = ep_in.wMaxPacketSize
def send(cmd: str, timeout=5000):
b = cmd.encode('ascii')
if not b.endswith(b'\n'):
b += b'\n'
dev.write(ep_out, b, timeout=timeout)
resp = b''
while True:
try:
data = dev.read(ep_in, MAXPKT, timeout=timeout)
if not data: break
resp += data.tobytes()
if len(data) < MAXPKT: break
except usb.core.USBError as e:
if e.errno == 110: break
raise
return resp
def reply(cmd: str) -> str:
r = send(cmd)
if not r:
return "(无响应)"
# 尝试 ASCII 解码
try:
text = r.decode('ascii').strip()
return f"{text} ({len(r)}B)"
except UnicodeDecodeError:
return f"HEX[{len(r)}B] {binascii.hexlify(r[:64], ' ').decode()}{'...' if len(r)>64 else ''}"
print(f"已连接 max_pkt={MAXPKT}")
print("直接输入 SCPI 命令 (如 :RUNning? 或 :DATA:WAVE:SCREen:CH1?)")
print("/raw cmd 发送原始命令不自动加 ?/\\n")
print("/quit 退出\n")
try:
while True:
try:
line = input(">> ").strip()
except (EOFError, KeyboardInterrupt):
break
if not line:
continue
if line == '/quit':
break
if line.startswith('/raw '):
b = line[5:].encode('ascii')
dev.write(ep_out, b, timeout=5000)
# 读响应
resp = b''
while True:
try:
d = dev.read(ep_in, MAXPKT, timeout=1000)
if not d: break
resp += d.tobytes()
if len(d) < MAXPKT: break
except usb.core.USBError as e:
if e.errno == 110: break
raise
print(f"HEX[{len(resp)}B] {binascii.hexlify(resp[:128], ' ').decode()}{'...' if len(resp)>128 else ''}")
continue
try:
print(reply(line))
except Exception as e:
print(f"错误: {e}")
except KeyboardInterrupt:
pass
finally:
usb.util.dispose_resources(dev)
print("\n已断开")

查看文件

@ -0,0 +1,176 @@
#!/usr/bin/env python3
"""
声速测定 — 时差法独立工具
通过原生 PyUSB + SCPI 协议获取 CH1 和 CH2 原始波形数据,
使用时差法 (第一个脉冲峰时间差) 计算声波传递时间,
并在 GUI 中展示原始波形与标记的峰值位置。
用法:
python -m tools.sound_speed_detector # 默认 VID/PID
python -m tools.sound_speed_detector --vid 0x5345 --pid 0x1234
python -m tools.sound_speed_detector --height 0.3 --prominence 0.2
工作流程:
1. 连接示波器 (PyUSB)
2. 获取设备信息 (IDN)
3. 获取 HEAD (时基、电压档位、偏移等)
4. 获取 CH1 和 CH2 原始波形
5. ADC → 电压转换 + 时间轴构建
6. 脉冲峰检测 (scipy.signal.find_peaks)
7. GUI 展示
"""
from __future__ import annotations
import argparse
import sys
import time
from pathlib import Path
from typing import Optional
import numpy as np
_SCRIPT_DIR = Path(__file__).resolve().parent
# 确保可以 import 本包内部的模块
if str(_SCRIPT_DIR.parent) not in sys.path:
sys.path.insert(0, str(_SCRIPT_DIR.parent))
from sound_speed_detector.scpi import ScpiDevice, SCPIError
from sound_speed_detector.waveform import (
fetch_head,
fetch_waveform,
adc_to_voltage,
build_time_axis,
HeadInfo,
)
from sound_speed_detector.peaks import compute_time_difference
from sound_speed_detector.gui import run_gui
def parse_args() -> argparse.Namespace:
p = argparse.ArgumentParser(
description="声速测定 — 时差法 (PyUSB + SCPI 独立工具)"
)
p.add_argument("--vid", type=str, default="0x5345",
help="USB Vendor ID (默认: 0x5345)")
p.add_argument("--pid", type=str, default="0x1234",
help="USB Product ID (默认: 0x1234)")
p.add_argument("--height", type=float, default=0.25,
help="峰值检测高度比例 (默认: 0.25)")
p.add_argument("--prominence", type=float, default=0.15,
help="峰值检测显著度比例 (默认: 0.15)")
p.add_argument("--distance", type=int, default=10,
help="峰间最小距离/样本数 (默认: 10)")
p.add_argument("--no-gui", action="store_true",
help="跳过 GUI,仅打印终端结果")
return p.parse_args()
def main() -> None:
args = parse_args()
vid = int(args.vid, 16) if args.vid.startswith("0x") else int(args.vid)
pid = int(args.pid, 16) if args.pid.startswith("0x") else int(args.pid)
print("=" * 55)
print(" 声速测定 — 时差法")
print(" PyUSB + SCPI 独立采集工具")
print("=" * 55)
# ── 1. 连接示波器 ──
print(f"\n[1/5] 连接示波器 (VID=0x{vid:04X}, PID=0x{pid:04X}) ...")
try:
dev = ScpiDevice(vid=vid, pid=pid)
dev.open()
except SCPIError as e:
print(f" 连接失败: {e}", file=sys.stderr)
sys.exit(1)
try:
# ── 2. 获取设备信息 ──
print("[2/5] 获取设备信息 ...")
device_id = dev.idn()
print(f" 设备: {device_id}")
# ── 3. 获取 HEAD (示波器参数) ──
print("[3/5] 获取示波器参数 (HEAD) ...")
head = fetch_head(dev)
print(f" 时基: {head.timebase_scale}")
for ch in head.channels:
print(f" {ch.name}: {ch.scale} "
f"(offset={ch.offset}, coupling={ch.coupling}, probe={ch.probe})")
print(f" 数据点数: {head.datalen}")
# ── 4. 获取波形 ──
print("[4/5] 获取 CH1 & CH2 波形 ...")
ch1_adc = fetch_waveform(dev, 1)
time.sleep(0.05)
ch2_adc = fetch_waveform(dev, 2)
print(f" CH1: {len(ch1_adc)} 点 (ADC 范围 [{ch1_adc.min():.0f}, {ch1_adc.max():.0f}])")
print(f" CH2: {len(ch2_adc)} 点 (ADC 范围 [{ch2_adc.min():.0f}, {ch2_adc.max():.0f}])")
# ── 转换 ──
ch1_param = head.get_channel("ch1")
ch2_param = head.get_channel("ch2")
# 通过 SCPI 单独查询 offset 以获得更精确的偏移电压
ch1_off_scpi: Optional[float] = None
ch2_off_scpi: Optional[float] = None
try:
ch1_off_scpi = dev.send_float(":CH1:OFFSET?")
except Exception:
pass
try:
ch2_off_scpi = dev.send_float(":CH2:OFFSET?")
except Exception:
pass
ch1_vdiv = ch1_param.vdiv if ch1_param else 1.0
ch1_off = ch1_off_scpi if ch1_off_scpi is not None else (ch1_param.offset_volts if ch1_param else 0.0)
ch2_vdiv = ch2_param.vdiv if ch2_param else 1.0
ch2_off = ch2_off_scpi if ch2_off_scpi is not None else (ch2_param.offset_volts if ch2_param else 0.0)
v_ch1 = adc_to_voltage(ch1_adc, ch1_vdiv, ch1_off)
v_ch2 = adc_to_voltage(ch2_adc, ch2_vdiv, ch2_off)
tb_sec = head.tb_scale_sec
t_ch1 = build_time_axis(len(ch1_adc), tb_sec)
t_ch2 = build_time_axis(len(ch2_adc), tb_sec)
# ── 5. 峰值检测 ──
print("[5/5] 峰值检测 & 时间差计算 ...")
result = compute_time_difference(
t_ch1, v_ch1, t_ch2, v_ch2,
height_factor=args.height,
prominence_factor=args.prominence,
distance=args.distance,
)
if result.get("delta_t") is not None:
dt_us = result["delta_t"] * 1e6
print(f" CH1 第一脉冲峰: {result['ch1_peak_time']*1000:.4f} ms")
print(f" CH2 第一脉冲峰: {result['ch2_peak_time']*1000:.4f} ms")
print(f" Δt = {result['delta_t']*1000:.4f} ms = {dt_us:.2f} μs")
else:
print(f" {result.get('error', '检测失败')}")
head_info = {
"timebase": head.timebase_scale,
"ch1_scale": ch1_param.scale if ch1_param else "N/A",
"ch2_scale": ch2_param.scale if ch2_param else "N/A",
}
finally:
dev.close()
print("\n 示波器已断开")
if args.no_gui:
print("\n(已跳过 GUI)")
else:
print("\n启动 GUI ...")
run_gui(t_ch1, v_ch1, t_ch2, v_ch2, result, device_id, head_info)
if __name__ == "__main__":
main()

查看文件

@ -0,0 +1,462 @@
"""
示波器波形 GUI — 展示 CH1/CH2 原始波形、脉冲峰标记、时间差结果。
支持:
- 相对模式: (v - baseline) * factor + baseline,放大脉冲偏离
- X/Y 独立缩放
- 模式/倍数切换即时重绘
"""
from __future__ import annotations
from typing import Optional
import numpy as np
from PyQt5 import QtWidgets, QtCore, QtGui
import pyqtgraph as pg
__all__ = ["ResultWindow", "run_gui"]
CH1_COLOR = (255, 150, 50)
CH2_COLOR = (80, 220, 100)
CH1_MARKER_COLOR = (255, 70, 30)
CH2_MARKER_COLOR = (30, 190, 80)
DELTA_COLOR = "#00e5ff"
BG_COLOR = "#12122a"
INFO_BG = "#1a1a3e"
TEXT_COLOR = "#e0e0e0"
WAVEFORM_LINE_WIDTH = 2.5
MARKER_SIZE = 22
MARKER_PEN_WIDTH = 2.5
VLINE_WIDTH = 2.0
DEFAULT_FACTOR = 5
ZOOM_MIN = 10
ZOOM_MAX = 5000
ZOOM_DEFAULT = 100
def _spin_style(color: str) -> str:
return (
f"QSpinBox {{ background: #222244; color: {color}; border: 1px solid #444477; "
"border-radius: 4px; padding: 2px 6px; font-size: 13px; font-weight: bold; }}"
)
class ResultWindow(QtWidgets.QMainWindow):
"""声速测定 — 时差法结果展示窗口。"""
def __init__(
self,
t_ch1: np.ndarray,
v_ch1: np.ndarray,
t_ch2: np.ndarray,
v_ch2: np.ndarray,
result: dict,
device_id: str = "",
head_info: Optional[dict] = None,
):
super().__init__()
self._t_ch1 = t_ch1
self._t_ch2 = t_ch2
self._v_ch1_raw = v_ch1
self._v_ch2_raw = v_ch2
self._baseline_ch1 = float(np.median(v_ch1))
self._baseline_ch2 = float(np.median(v_ch2))
self.result = result
self.device_id = device_id
self.head_info = head_info or {}
self._mode = "relative"
self._factor = DEFAULT_FACTOR
self._x_zoom = ZOOM_DEFAULT
self._y_zoom = ZOOM_DEFAULT
self._added_items: list = [] # 每次 _redraw 添加的所有 plot items
self._legend = None
self._setup()
# ── 电压变换 ──────────────────────────────────────────────
def _transform(self, v: np.ndarray, baseline: float) -> np.ndarray:
if self._mode == "relative":
return (v - baseline) * self._factor + baseline
return v
@property
def _v_ch1(self) -> np.ndarray:
return self._transform(self._v_ch1_raw, self._baseline_ch1)
@property
def _v_ch2(self) -> np.ndarray:
return self._transform(self._v_ch2_raw, self._baseline_ch2)
def _peak_voltage(self, ch: str) -> Optional[float]:
v = self.result.get(f"{ch}_peak_voltage")
if v is None:
return None
base = self._baseline_ch1 if ch == "ch1" else self._baseline_ch2
return self._transform(np.array([v]), base)[0] if self._mode == "relative" else v
# ── UI 搭建 ───────────────────────────────────────────────
def _setup(self) -> None:
self.setWindowTitle("声速测定 — 时差法")
self.resize(1400, 900)
cw = QtWidgets.QWidget()
self.setCentralWidget(cw)
layout = QtWidgets.QVBoxLayout(cw)
layout.setContentsMargins(10, 10, 10, 10)
layout.setSpacing(8)
layout.addWidget(self._make_info_bar())
layout.addWidget(self._make_zoom_bar())
self._plot_widget = pg.PlotWidget()
self._plot_widget.setBackground(BG_COLOR)
self._plot_widget.showGrid(x=True, y=True, alpha=0.4)
self._plot_widget.setLabel("bottom", "时间", units="s")
axis_font = QtGui.QFont("sans-serif", 11)
self._plot_widget.getAxis("bottom").setTickFont(axis_font)
self._plot_widget.getAxis("left").setTickFont(axis_font)
for ax_name in ("bottom", "left"):
self._plot_widget.getAxis(ax_name).label.setFont(
QtGui.QFont("sans-serif", 12, QtGui.QFont.Bold))
self._plot_widget.getPlotItem().titleLabel.item.setFont(
QtGui.QFont("sans-serif", 14, QtGui.QFont.Bold))
self._legend = self._plot_widget.addLegend(
offset=(12, 12),
brush=pg.mkBrush("#1a1a2eCC"),
pen=pg.mkPen("#444477", width=1),
labelTextSize="12pt",
)
self._update_axis_label()
self._redraw()
layout.addWidget(self._plot_widget, stretch=1)
layout.addWidget(self._make_result_bar())
# ── 信息栏 ────────────────────────────────────────────────
def _make_info_bar(self) -> QtWidgets.QWidget:
bar = QtWidgets.QWidget()
bar.setStyleSheet(f"background: {INFO_BG}; border-radius: 6px; padding: 6px;")
bar.setFixedHeight(46)
hbox = QtWidgets.QHBoxLayout(bar)
hbox.setContentsMargins(12, 2, 12, 2)
hbox.setSpacing(20)
for title, value in [
("设备", self.device_id or "N/A"),
("时基", self.head_info.get("timebase", "N/A")),
("CH1", self.head_info.get("ch1_scale", "N/A")),
("CH2", self.head_info.get("ch2_scale", "N/A")),
]:
lbl = QtWidgets.QLabel(f"<b>{title}:</b> {value}")
lbl.setStyleSheet(f"color: {TEXT_COLOR}; font-size: 13px;")
hbox.addWidget(lbl)
hbox.addStretch()
hbox.addWidget(QtWidgets.QLabel(
"<b>显示:</b>", styleSheet=f"color:{TEXT_COLOR};font-size:13px;"))
self._mode_cb = QtWidgets.QComboBox()
self._mode_cb.addItems(["相对模式", "绝对模式"])
self._mode_cb.setCurrentIndex(0)
self._mode_cb.setStyleSheet(
"QComboBox { background:#222244; color:#e0e0e0; border:1px solid #444477; "
"border-radius:4px; padding:1px 6px; font-size:12px; }"
"QComboBox::drop-down { border:none; }"
"QComboBox QAbstractItemView { background:#222244; color:#e0e0e0; "
"selection-background-color:#444477; }")
self._mode_cb.currentIndexChanged.connect(self._on_mode_changed)
hbox.addWidget(self._mode_cb)
self._factor_sb = QtWidgets.QSpinBox()
self._factor_sb.setRange(1, 50)
self._factor_sb.setValue(DEFAULT_FACTOR)
self._factor_sb.setPrefix("×")
self._factor_sb.setStyleSheet(_spin_style("#00e5ff"))
self._factor_sb.valueChanged.connect(self._on_factor_changed)
hbox.addWidget(self._factor_sb)
return bar
# ── 缩放栏 ────────────────────────────────────────────────
def _make_zoom_bar(self) -> QtWidgets.QWidget:
bar = QtWidgets.QWidget()
bar.setStyleSheet(f"background: {INFO_BG}; border-radius: 6px; padding: 4px;")
bar.setFixedHeight(40)
hbox = QtWidgets.QHBoxLayout(bar)
hbox.setContentsMargins(12, 2, 12, 2)
hbox.setSpacing(10)
for label, attr, color in [
("X 缩放", "_x_zoom_sb", "#ff9800"),
("Y 缩放", "_y_zoom_sb", "#4fc3f7"),
]:
lbl = QtWidgets.QLabel(f"<b>{label}:</b>")
lbl.setStyleSheet(f"color: {color}; font-size: 13px;")
hbox.addWidget(lbl)
sb = QtWidgets.QSpinBox()
sb.setRange(ZOOM_MIN, ZOOM_MAX)
sb.setValue(ZOOM_DEFAULT)
sb.setSuffix("%")
sb.setSingleStep(10)
sb.setStyleSheet(_spin_style(color))
sb.valueChanged.connect(
self._on_x_zoom_changed if "x" in attr else self._on_y_zoom_changed
)
setattr(self, attr, sb)
hbox.addWidget(sb)
hbox.addStretch()
reset_btn = QtWidgets.QPushButton("重置缩放")
reset_btn.setStyleSheet(
"QPushButton { background:#333355; color:#e0e0e0; border:1px solid #555577; "
"border-radius:4px; padding:3px 12px; font-size:12px; }"
"QPushButton:hover { background:#444477; }")
reset_btn.clicked.connect(self._reset_zoom)
hbox.addWidget(reset_btn)
return bar
# ── 回调 ──────────────────────────────────────────────────
def _on_mode_changed(self, idx: int) -> None:
self._mode = "relative" if idx == 0 else "absolute"
self._factor_sb.setEnabled(self._mode == "relative")
self._factor_sb.setStyleSheet(
_spin_style("#00e5ff") if self._mode == "relative"
else _spin_style("#666688"))
self._update_axis_label()
self._redraw()
def _on_factor_changed(self, value: int) -> None:
if self._mode != "relative":
return
self._factor = value
self._update_axis_label()
self._redraw()
def _on_x_zoom_changed(self, value: int) -> None:
self._x_zoom = value
self._apply_zoom()
def _on_y_zoom_changed(self, value: int) -> None:
self._y_zoom = value
self._apply_zoom()
def _reset_zoom(self) -> None:
self._x_zoom_sb.setValue(ZOOM_DEFAULT)
self._y_zoom_sb.setValue(ZOOM_DEFAULT)
def _update_axis_label(self) -> None:
if self._mode == "relative":
self._plot_widget.setLabel(
"left", f"电压 (×{self._factor} 相对偏离)", units="V")
self._plot_widget.setTitle(
f"CH1 & CH2 波形 — 相对模式 ×{self._factor}")
else:
self._plot_widget.setLabel("left", "电压", units="V")
self._plot_widget.setTitle("CH1 & CH2 原始波形")
# ── 缩放应用 ──────────────────────────────────────────────
def _apply_zoom(self) -> None:
vb = self._plot_widget.getPlotItem().getViewBox()
# autoRange 后取当前范围, 再按比例缩放
full_x_range = [float(self._t_ch1[0]), float(self._t_ch1[-1])]
cx = (full_x_range[0] + full_x_range[1]) / 2
half_w = (full_x_range[1] - full_x_range[0]) / 2
x_factor = ZOOM_DEFAULT / max(self._x_zoom, 1)
vb.setXRange(cx - half_w * x_factor, cx + half_w * x_factor, padding=0)
full_y_range = vb.viewRange()[1]
cy = (full_y_range[0] + full_y_range[1]) / 2
half_h = (full_y_range[1] - full_y_range[0]) / 2
y_factor = ZOOM_DEFAULT / max(self._y_zoom, 1)
if half_h > 1e-12:
vb.setYRange(cy - half_h * y_factor, cy + half_h * y_factor, padding=0)
# ── 重绘 ──────────────────────────────────────────────────
def _redraw(self) -> None:
pi = self._plot_widget.getPlotItem()
for item in self._added_items:
pi.removeItem(item)
self._added_items.clear()
self._plot_curves()
self._plot_delta_region()
self._plot_peaks()
self._plot_widget.autoRange(padding=0.08)
self._apply_zoom()
def _add(self, item) -> None:
self._plot_widget.addItem(item)
self._added_items.append(item)
def _plot_curves(self) -> None:
if len(self._t_ch1) > 0:
curve = pg.PlotCurveItem(
self._t_ch1, self._v_ch1,
pen=pg.mkPen(color=CH1_COLOR, width=WAVEFORM_LINE_WIDTH),
name="CH1",
)
self._add(curve)
if len(self._t_ch2) > 0:
curve = pg.PlotCurveItem(
self._t_ch2, self._v_ch2,
pen=pg.mkPen(color=CH2_COLOR, width=WAVEFORM_LINE_WIDTH),
name="CH2",
)
self._add(curve)
def _plot_delta_region(self) -> None:
ch1_time = self.result.get("ch1_peak_time")
ch2_time = self.result.get("ch2_peak_time")
if None in (ch1_time, ch2_time):
return
region = pg.LinearRegionItem(
values=(min(ch1_time, ch2_time), max(ch1_time, ch2_time)),
orientation="vertical",
brush=pg.mkBrush(0, 229, 255, 40),
pen=pg.mkPen(None),
movable=False,
)
region.setZValue(-10)
self._add(region)
def _plot_peaks(self) -> None:
t1 = self.result.get("ch1_peak_time")
t2 = self.result.get("ch2_peak_time")
dt = self.result.get("delta_t")
v1 = self._peak_voltage("ch1")
v2 = self._peak_voltage("ch2")
pi = self._plot_widget.getPlotItem()
label_font = QtGui.QFont("sans-serif", 11, QtGui.QFont.Bold)
for ch, t, v, clr, anchor, name in [
("ch1", t1, v1, CH1_MARKER_COLOR, (0.5, 0), "CH1 峰"),
("ch2", t2, v2, CH2_MARKER_COLOR, (0.5, 1), "CH2 峰"),
]:
if t is None or v is None:
continue
scatter = pg.ScatterPlotItem(
[t], [v],
symbol="t", size=MARKER_SIZE,
brush=pg.mkBrush(clr),
pen=pg.mkPen("w", width=MARKER_PEN_WIDTH),
name=name,
)
self._add(scatter)
vline = pg.InfiniteLine(
pos=t, angle=90,
pen=pg.mkPen(clr, width=VLINE_WIDTH, style=QtCore.Qt.DashLine),
)
self._add(vline)
if self._mode == "relative":
label_text = f"{name}\n{t*1000:.3f} ms\n×{self._factor} 放大"
else:
label_text = f"{name}\n{t*1000:.3f} ms"
label = pg.TextItem(label_text, color=clr, anchor=anchor)
label.setFont(label_font)
label.setPos(t, v)
self._add(label)
if t1 is not None and t2 is not None and dt is not None:
mid_t = (t1 + t2) / 2
y_r = pi.viewRange()[1]
mid_y = (y_r[0] + y_r[1]) / 2
dt_label = pg.TextItem(
f"Δt = {dt*1e6:.1f} μs",
color=DELTA_COLOR, anchor=(0.5, 0.5),
)
dt_label.setFont(QtGui.QFont("sans-serif", 14, QtGui.QFont.Bold))
dt_label.setPos(mid_t, mid_y)
self._add(dt_label)
for angle, pos in [(180, t1), (0, t2)]:
arrow = pg.ArrowItem(
angle=angle, tipAngle=35, headLen=18, tailLen=0,
brush=pg.mkBrush(DELTA_COLOR),
pen=pg.mkPen(DELTA_COLOR, width=2),
)
arrow.setPos(pos, mid_y)
self._add(arrow)
conn = pg.PlotCurveItem(
[t1, t2], [mid_y, mid_y],
pen=pg.mkPen(DELTA_COLOR, width=2.5),
)
self._add(conn)
# ── 结果栏 ────────────────────────────────────────────────
def _make_result_bar(self) -> QtWidgets.QWidget:
bar = QtWidgets.QWidget()
bar.setStyleSheet(f"background:{INFO_BG}; border-radius:6px; padding:8px;")
bar.setFixedHeight(76)
hbox = QtWidgets.QHBoxLayout(bar)
hbox.setContentsMargins(14, 6, 14, 6)
hbox.setSpacing(24)
dt = self.result.get("delta_t")
if dt is not None:
main_lbl = QtWidgets.QLabel(
f"<span style='font-size:26px;font-weight:bold;color:#00e5ff;'>"
f"Δt = {dt*1000:.4f} ms</span>"
f"<span style='font-size:20px;font-weight:bold;color:#4fc3f7;'>"
f" = {dt*1e6:.2f} μs</span>"
)
else:
main_lbl = QtWidgets.QLabel(
f"<span style='font-size:18px;color:#ef5350;'>"
f"{self.result.get('error','未知错误')}</span>"
)
hbox.addWidget(main_lbl)
hbox.addStretch()
parts = []
for ch, label in [("ch1", "CH1"), ("ch2", "CH2")]:
t = self.result.get(f"{ch}_peak_time")
v = self.result.get(f"{ch}_peak_voltage")
if t is not None and v is not None:
parts.append(f"{label} 峰 @ {t*1000:.4f} ms ({v:.3f} V)")
detail = QtWidgets.QLabel(" ".join(parts))
detail.setStyleSheet("color:#b0b0cc; font-size:13px;")
hbox.addWidget(detail)
return bar
def run_gui(
t_ch1: np.ndarray,
v_ch1: np.ndarray,
t_ch2: np.ndarray,
v_ch2: np.ndarray,
result: dict,
device_id: str = "",
head_info: Optional[dict] = None,
) -> None:
import sys as _sys
app = QtWidgets.QApplication(_sys.argv)
win = ResultWindow(t_ch1, v_ch1, t_ch2, v_ch2, result, device_id, head_info)
win.show()
app.exec_()

查看文件

@ -0,0 +1,116 @@
"""
峰值检测模块 — 使用时差法定位 CH1 和 CH2 第一个脉冲峰。
使用 scipy.signal.find_peaks 进行峰值检测,选择高度和显著度足够的峰,
从各自通道中选出第一个有效峰,计算时间差。
"""
from __future__ import annotations
from typing import Optional, Tuple
import numpy as np
from scipy.signal import find_peaks
__all__ = ["find_first_pulse_peak", "compute_time_difference"]
def find_first_pulse_peak(
voltage: np.ndarray,
time_s: np.ndarray,
height_factor: float = 0.25,
prominence_factor: float = 0.15,
distance: int = 10,
) -> Optional[Tuple[int, float]]:
"""在信号中查找第一个脉冲峰。
算法:
1. 用绝对偏离 (|V - median(V)|) 作为峰值检测的输入
2. 设 height = height_factor * max_abs,确保只检出显著峰
3. 设 prominence 过滤毛刺
4. 取索引最小的峰作为 "第一个脉冲峰"
Args:
voltage: 电压数组 (V)
time_s: 时间数组 (s)
height_factor: 峰值高度比例 (相对于最大绝对偏离)
prominence_factor: 峰显著度比例
distance: 峰间最小距离 (样本数)
Returns:
(峰值索引, 峰值到达时间) 或 None (无信号)
"""
if len(voltage) < 3:
return None
baseline = np.median(voltage)
abs_dev = np.abs(voltage - baseline)
max_dev = np.max(abs_dev)
if max_dev < 1e-6:
return None # 无信号
height = max_dev * height_factor
prominence = max_dev * prominence_factor
peaks, props = find_peaks(
abs_dev,
height=height,
prominence=prominence,
distance=distance,
)
if len(peaks) == 0:
# 放松条件再试一次
peaks, props = find_peaks(abs_dev, height=max_dev * 0.1, distance=distance)
if len(peaks) == 0:
# 最终回退: 直接用最大偏离点
idx = int(np.argmax(abs_dev))
return (idx, float(time_s[idx]))
first_peak = peaks[0]
return (int(first_peak), float(time_s[first_peak]))
def compute_time_difference(
t_ch1: np.ndarray,
v_ch1: np.ndarray,
t_ch2: np.ndarray,
v_ch2: np.ndarray,
**kwargs,
) -> dict:
"""计算 CH1 和 CH2 第一个脉冲峰之间的时间差 (时差法)。
Returns:
dict with keys:
ch1_peak_idx, ch1_peak_time, ch1_peak_voltage
ch2_peak_idx, ch2_peak_time, ch2_peak_voltage
delta_t (时间差, s)
"""
result_ch1 = find_first_pulse_peak(v_ch1, t_ch1, **kwargs)
result_ch2 = find_first_pulse_peak(v_ch2, t_ch2, **kwargs)
if result_ch1 is None or result_ch2 is None:
return {
"ch1_peak_idx": None,
"ch1_peak_time": None,
"ch1_peak_voltage": None,
"ch2_peak_idx": None,
"ch2_peak_time": None,
"ch2_peak_voltage": None,
"delta_t": None,
"error": "未能检测到一个或两个通道的脉冲峰",
}
ch1_idx, ch1_time = result_ch1
ch2_idx, ch2_time = result_ch2
return {
"ch1_peak_idx": ch1_idx,
"ch1_peak_time": ch1_time,
"ch1_peak_voltage": float(v_ch1[ch1_idx]),
"ch2_peak_idx": ch2_idx,
"ch2_peak_time": ch2_time,
"ch2_peak_voltage": float(v_ch2[ch2_idx]),
"delta_t": ch2_time - ch1_time,
}

查看文件

@ -0,0 +1,185 @@
"""
原生 PyUSB SCPI 设备通信层 — 直接操作 USB 批量端点,
不依赖任何上层封装。
兼容 OWON NDS102U (小写 key HEAD) 和 NDS202E (大写 key HEAD, -> 后缀)。
"""
from __future__ import annotations
import re
from typing import Optional
import usb.core
import usb.util
__all__ = [
"ScpiDevice",
"parse_scale_str",
"parse_probe_ratio",
"extract_numeric",
"SCPIError",
]
DEFAULT_VID = 0x5345
DEFAULT_PID = 0x1234
DEFAULT_TIMEOUT_MS = 5000
_SCALE_RE = re.compile(r"([\d.]+)\s*([numk]?[sv])\s*", re.IGNORECASE)
_UNIT_MULTIPLIERS: dict[str, float] = {
"nv": 1e-9, "uv": 1e-6, "mv": 1e-3, "v": 1.0, "kv": 1e3,
"ns": 1e-9, "us": 1e-6, "ms": 1e-3, "s": 1.0, "ks": 1e3,
}
_NUMERIC_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")
_RESP_SUFFIX_RE = re.compile(rb"\s*->\s*$")
class SCPIError(RuntimeError):
"""SCPI 通信错误。"""
pass
def parse_scale_str(raw: str) -> float:
"""解析电压/时基档位字符串,如 '5.00mv' → 0.005, '1v' → 1.0, '200us' → 2e-4。"""
m = _SCALE_RE.search(raw.lower().strip())
if m:
return float(m.group(1)) * _UNIT_MULTIPLIERS.get(m.group(2), 1.0)
try:
return float(raw)
except (ValueError, TypeError):
return 1.0
def parse_probe_ratio(raw: str) -> float:
"""解析探头比例字符串,如 '10x' → 10.0, '1x' → 1.0。"""
try:
return float(raw.strip().lower().rstrip("x"))
except (ValueError, TypeError):
return 1.0
def extract_numeric(text: str) -> Optional[float]:
"""从文本中提取第一个数值。"""
m = _NUMERIC_RE.search(text)
if m is None:
return None
try:
return float(m.group())
except (ValueError, OverflowError):
return None
def _strip_resp_suffix(data: bytes) -> bytes:
"""去除 NDS202E 响应末尾的 '->' 后缀。"""
return _RESP_SUFFIX_RE.sub(b"", data)
class ScpiDevice:
"""原生 PyUSB SCPI 通信器 — 直接操作 USB 批量端点。"""
def __init__(self, vid: int = DEFAULT_VID, pid: int = DEFAULT_PID):
self._vid = vid
self._pid = pid
self._dev: Optional[usb.core.Device] = None
self._ep_out: Optional[usb.core.Endpoint] = None
self._ep_in: Optional[usb.core.Endpoint] = None
self._max_pkt: int = 512
self._detached: list[int] = []
def open(self) -> None:
dev = usb.core.find(idVendor=self._vid, idProduct=self._pid)
if dev is None:
raise SCPIError(
f"设备未找到 (VID=0x{self._vid:04X}, PID=0x{self._pid:04X}). "
"请检查 USB 连接和权限。"
)
self._dev = dev
for cfg in self._dev:
for intf in cfg:
ifn = intf.bInterfaceNumber
if self._dev.is_kernel_driver_active(ifn):
self._dev.detach_kernel_driver(ifn)
self._detached.append(ifn)
self._dev.set_configuration()
intf = self._dev.get_active_configuration()[(0, 0)]
for ep in intf:
dir_ = usb.util.endpoint_direction(ep.bEndpointAddress)
if dir_ == usb.util.ENDPOINT_OUT:
self._ep_out = ep
elif dir_ == usb.util.ENDPOINT_IN:
self._ep_in = ep
if not self._ep_out or not self._ep_in:
raise SCPIError("未找到批量 IN/OUT 端点")
self._max_pkt = self._ep_in.wMaxPacketSize
def close(self) -> None:
if self._dev is None:
return
for ifn in self._detached:
try:
self._dev.attach_kernel_driver(ifn)
except usb.core.USBError:
pass
self._detached.clear()
try:
usb.util.dispose_resources(self._dev)
except Exception:
pass
self._dev = None
self._ep_out = None
self._ep_in = None
def __enter__(self):
self.open()
return self
def __exit__(self, *args):
self.close()
@property
def is_open(self) -> bool:
return self._dev is not None
def _flush_input(self) -> None:
try:
while True:
self._dev.read(self._ep_in, self._max_pkt, timeout=50)
except usb.core.USBError:
pass
def send(self, scpi: str, timeout: int = DEFAULT_TIMEOUT_MS) -> bytes:
"""发送 SCPI 命令,返回去除 '->' 后缀的原始响应字节。"""
if not scpi.endswith("\n"):
scpi += "\n"
self._flush_input()
self._dev.write(self._ep_out, scpi.encode("ascii"), timeout=timeout)
resp = b""
while True:
try:
data = self._dev.read(self._ep_in, self._max_pkt, timeout=timeout)
if not data:
break
resp += data.tobytes()
if len(data) < self._max_pkt:
break
except usb.core.USBError as e:
if e.errno == 110:
break
raise SCPIError(f"读取响应失败: {e}")
return _strip_resp_suffix(resp)
def send_text(self, scpi: str, timeout: int = DEFAULT_TIMEOUT_MS) -> str:
"""发送 SCPI 查询命令,返回解码后的文本。"""
return self.send(scpi, timeout).decode("ascii", errors="ignore").strip()
def send_float(self, scpi: str, timeout: int = DEFAULT_TIMEOUT_MS) -> Optional[float]:
"""发送 SCPI 查询命令,返回浮点数值。"""
text = self.send_text(scpi, timeout)
return extract_numeric(text)
def idn(self) -> str:
return self.send_text("*IDN?")

查看文件

@ -0,0 +1,199 @@
"""
波形数据解析与物理量转换模块。
负责:
- HEAD JSON 解析 → 时基 + 通道参数
- 波形数据解析 → 12-bit 有符号 ADC 数组
- ADC → 电压转换
- 时间轴构建
"""
from __future__ import annotations
import json
import struct
from dataclasses import dataclass, field
from typing import Optional
import numpy as np
from .scpi import (
ScpiDevice,
parse_scale_str,
parse_probe_ratio,
SCPIError,
)
__all__ = [
"ChannelParams",
"HeadInfo",
"fetch_head",
"fetch_waveform",
"parse_waveform",
"adc_to_voltage",
"build_time_axis",
]
_SCREEN_DIVS_H = 10
_SCREEN_DIVS_V = 8
_ADC_MAX = 0x1000 # 12-bit = 4096
@dataclass
class ChannelParams:
name: str = ""
display: bool = True
coupling: str = "dc"
probe: str = "1x"
scale: str = "1v"
offset: int = 0
inverse: bool = False
@property
def vdiv(self) -> float:
return parse_scale_str(self.scale)
@property
def probe_ratio(self) -> float:
return parse_probe_ratio(self.probe)
@property
def offset_volts(self) -> float:
return self.offset / 100.0 * self.vdiv
def parse_waveform(data: bytes) -> np.ndarray:
"""解析 CH<x> 波形数据为 12-bit 有符号 ADC 值。
兼容两种格式:
1) 4 字节 LE 长度前缀 + 2 字节/点 (SCPI DATA 子系统规范)
2) 纯 2 字节/点 无前缀 (某些固件版本)
ADC 值范围: [-2048, 2047]。
"""
_n = len(data)
if _n < 4:
raise ValueError(f"数据不足 4 字节 (实际 {_n})")
payload = data
# 尝试格式 1: 有长度前缀
hdr_len = struct.unpack("<I", data[:4])[0]
if 4 + hdr_len == _n and hdr_len % 2 == 0:
payload = data[4:]
elif 4 + hdr_len <= _n: # 容许末尾有填零
payload = data[4:4 + hdr_len]
else:
pass # 格式 2: 全部视为载荷
if len(payload) % 2 != 0:
payload = payload[:-1]
num_points = len(payload) // 2
if num_points == 0:
raise ValueError("空载荷")
raw = np.frombuffer(payload, dtype="<u2", count=num_points) & 0x0FFF
signed = np.where(raw >= 0x0800, raw.astype(np.float64) - _ADC_MAX,
raw.astype(np.float64))
return signed
def adc_to_voltage(adc: np.ndarray, vdiv: float,
offset_volts: float = 0.0) -> np.ndarray:
"""有符号 12-bit ADC → 电压 (V)。"""
return adc * (_SCREEN_DIVS_V * vdiv / _ADC_MAX) - offset_volts
def build_time_axis(num_points: int, tb_scale_sec: float) -> np.ndarray:
"""根据数据点数和时基构建时间轴 (s)。"""
if num_points <= 0:
return np.array([])
return np.arange(num_points) * (_SCREEN_DIVS_H * tb_scale_sec / num_points)
# ─── HEAD 解析 ────────────────────────────────────────────────────
def _get_key(obj: dict, *keys: str, default=None):
for k in keys:
if k in obj:
return obj[k]
ku = k.upper()
if ku in obj:
return obj[ku]
kl = k.lower()
if kl in obj:
return obj[kl]
return default
@dataclass
class HeadInfo:
timebase_scale: str = "1.0ms"
timebase_hoffset: int = 0
samplerate: str = "500ks/s"
datalen: int = 1520
channels: list[ChannelParams] = field(default_factory=list)
runstatus: str = "auto"
@property
def tb_scale_sec(self) -> float:
return parse_scale_str(self.timebase_scale)
def get_channel(self, name: str) -> Optional[ChannelParams]:
for ch in self.channels:
if ch.name.upper() == name.upper():
return ch
return None
def fetch_head(dev: ScpiDevice) -> HeadInfo:
"""通过 SCPI 获取 HEAD 并解析为 HeadInfo。"""
resp = dev.send(":DATA:WAVE:SCREen:HEAD?")
if not resp or len(resp) < 4:
raise SCPIError("HEAD 响应为空")
payload_len = struct.unpack("<I", resp[:4])[0]
payload = resp[4:]
if len(payload) < payload_len:
raise SCPIError(f"HEAD 载荷不足: 期望 {payload_len} 字节,实际 {len(payload)}")
payload = payload[:payload_len]
try:
raw = json.loads(payload.decode("ascii", errors="ignore").strip())
except (json.JSONDecodeError, UnicodeDecodeError) as e:
raise SCPIError(f"HEAD JSON 解析失败: {e}")
tb = _get_key(raw, "timebase", default={})
sp = _get_key(raw, "sample", default={})
channels = []
ch_list = _get_key(raw, "channel", default=[])
for ch in ch_list:
display_raw = _get_key(ch, "display", default="on")
inverse_raw = _get_key(ch, "inverse", default="off")
channels.append(ChannelParams(
name=_get_key(ch, "name", default=""),
display=str(display_raw).lower() == "on",
coupling=_get_key(ch, "coupling", default="dc"),
probe=_get_key(ch, "probe", default="1x"),
scale=_get_key(ch, "scale", default="1v"),
offset=_get_key(ch, "offset", default=0),
inverse=str(inverse_raw).lower() == "on",
))
return HeadInfo(
timebase_scale=_get_key(tb, "scale", default="1.0ms"),
timebase_hoffset=_get_key(tb, "hoffset", default=0),
samplerate=_get_key(sp, "samplerate", default="500ks/s"),
datalen=_get_key(sp, "datalen", default=1520),
channels=channels,
runstatus=_get_key(raw, "runstatus", default="auto"),
)
def fetch_waveform(dev: ScpiDevice, channel: int) -> np.ndarray:
"""通过 SCPI 获取指定通道波形数据 (ADC 值)。"""
resp = dev.send(f":DATA:WAVE:SCREen:CH{channel}?")
if not resp:
raise SCPIError(f"CH{channel} 响应为空")
return parse_waveform(resp)

414
backend/tools/survey_osc.py 普通文件
查看文件

@ -0,0 +1,414 @@
#!/usr/bin/env python3
"""示波器 SCPI 返回格式调研 — 原生 PyUSB 直接探测"""
import hashlib
import json
import struct
import sys
import time
import usb.core
import usb.util
VID, PID = 0x5345, 0x1234
TIMEOUT = 5000
# ── 连接 ──
dev = usb.core.find(idVendor=VID, idProduct=PID)
assert dev, "设备未找到"
for cfg in dev:
for intf in cfg:
ifn = intf.bInterfaceNumber
if dev.is_kernel_driver_active(ifn):
dev.detach_kernel_driver(ifn)
dev.set_configuration()
intf = dev.get_active_configuration()[(0, 0)]
ep_out = ep_in = None
for ep in intf:
d = usb.util.endpoint_direction(ep.bEndpointAddress)
if d == usb.util.ENDPOINT_OUT: ep_out = ep
elif d == usb.util.ENDPOINT_IN: ep_in = ep
assert ep_out and ep_in
MAXPKT = ep_in.wMaxPacketSize
def flush():
try:
while True:
dev.read(ep_in, MAXPKT, timeout=50)
except usb.core.USBError:
pass
def send(cmd: str, timeout=TIMEOUT) -> bytes:
if not cmd.endswith('\n'): cmd += '\n'
flush()
dev.write(ep_out, cmd.encode('ascii'), timeout=timeout)
resp = b''
while True:
try:
data = dev.read(ep_in, MAXPKT, timeout=timeout)
if not data: break
resp += data.tobytes()
if len(data) < MAXPKT: break
except usb.core.USBError as e:
if e.errno == 110: break
raise
return resp
def hex_dump(data: bytes, max_len: int = 128):
"""前 max_len 字节的 hex dump"""
show = data[:max_len]
lines = []
for i in range(0, len(show), 16):
chunk = show[i:i+16]
hex_str = ' '.join(f'{b:02x}' for b in chunk)
ascii_str = ''.join(chr(b) if 32 <= b < 127 else '.' for b in chunk)
lines.append(f' {i:04x}: {hex_str:<48s} {ascii_str}')
if len(data) > max_len:
lines.append(f' ... (共 {len(data)} 字节,仅显示前 {max_len})')
return '\n'.join(lines)
def section(title: str):
print(f"\n{'='*70}")
print(f" {title}")
print(f"{'='*70}")
# ═══════════════════════════════════════════════════════════════════
# 1. *IDN?
# ═══════════════════════════════════════════════════════════════════
section("1. *IDN? — 设备身份")
resp = send('*IDN?')
print(f" 原始字节长度: {len(resp)}")
print(f" 原始 (hex): {resp.hex()}")
print(f" 解码: {resp.decode('ascii', 'ignore').strip()!r}")
# ═══════════════════════════════════════════════════════════════════
# 2. HEAD 完整原始
# ═══════════════════════════════════════════════════════════════════
section("2. :DATA:WAVE:SCREen:HEAD? — 波形文件头")
resp = send(':DATA:WAVE:SCREen:HEAD?')
print(f" 原始字节总长度: {len(resp)}")
print(f" 前 60 字节 hex dump:")
print(hex_dump(resp, 60))
# 解析前 4 字节
if len(resp) >= 4:
declared_len = struct.unpack('<I', resp[:4])[0]
payload = resp[4:]
print(f"\n 前 4 字节 (LE uint32) = {declared_len}")
print(f" 载荷实际长度 = {len(payload)}")
print(f" 长度匹配: {'YES' if declared_len == len(payload) else 'NO (差异: ' + str(len(payload) - declared_len) + ')'}")
try:
text = payload.decode('ascii', errors='replace')
print(f"\n 载荷 (解码后):")
print(f" {text[:500]}")
# 尝试 JSON 解析
try:
parsed = json.loads(text.strip())
print(f"\n JSON 解析成功。顶层 key: {list(parsed.keys())}")
ch_list = parsed.get('CHANNEL', [])
print(f" CHANNEL 数量: {len(ch_list)}")
for ch in ch_list:
print(f" {ch.get('NAME')}: SCALE={ch.get('SCALE')}, OFFSET={ch.get('OFFSET')}, "
f"PROBE={ch.get('PROBE')}, COUPLING={ch.get('COUPLING')}, "
f"DISPLAY={ch.get('DISPLAY')}")
except json.JSONDecodeError as e:
print(f" JSON 解析失败: {e}")
# 尝试找 JSON 边界
i = text.find('{')
j = text.rfind('}')
if i >= 0 and j > i:
print(f" 尝试截取 [{i}:{j+1}] 后解析:")
try:
parsed = json.loads(text[i:j+1])
print(f" 截取后 JSON 解析成功: {json.dumps(parsed, indent=2, ensure_ascii=False)[:500]}")
except:
print(" 截取后仍失败")
except Exception as e:
print(f" 解码失败: {e}")
# ═══════════════════════════════════════════════════════════════════
# 3. CH2 波形数据
# ═══════════════════════════════════════════════════════════════════
section("3. :DATA:WAVE:SCREen:CH2? — CH2 波形数据")
resp = send(':DATA:WAVE:SCREen:CH2?')
print(f" 原始字节总长度: {len(resp)}")
print(f" 前 32 字节 hex dump:")
print(hex_dump(resp, 32))
if len(resp) >= 4:
declared_len = struct.unpack('<I', resp[:4])[0]
payload = resp[4:]
print(f"\n 前 4 字节 (LE uint32) = {declared_len}")
print(f" 载荷实际长度 = {len(payload)}")
# 检查无前缀格式 (直接 12-bit 数据)
usable = len(resp) if len(resp) % 2 == 0 else len(resp) - 1
raw_noprefix = struct.unpack(f'<{usable//2}H', resp[:usable])
raw_noprefix = [v & 0x0FFF for v in raw_noprefix]
print(f"\n [无前缀格式] 总共 {usable//2} 个点 (12-bit)")
print(f" 前 10 个 ADC 值: {raw_noprefix[:10]}")
print(f" 后 10 个 ADC 值: {raw_noprefix[-10:]}")
print(f" ADC 范围: [{min(raw_noprefix)}, {max(raw_noprefix)}]")
if declared_len == len(payload):
print(f" [有前缀格式] 载荷 {declared_len} bytes, {declared_len//2} 个点")
raw_prefixed = struct.unpack(f'<{len(payload)//2}H', payload)
raw_prefixed = [v & 0x0FFF for v in raw_prefixed]
print(f" 前 10 个 ADC 值: {raw_prefixed[:10]}")
print(f" 后 10 个 ADC 值: {raw_prefixed[-10:]}")
print(f" ADC 范围: [{min(raw_prefixed)}, {max(raw_prefixed)}]")
# ═══════════════════════════════════════════════════════════════════
# 4. 各种 MEASUrement 查询
# ═══════════════════════════════════════════════════════════════════
section("4. :MEASUrement 查询 (CH2)")
items = [
("MAX", "最大值"),
("MIN", "最小值"),
("PKPK", "峰峰值"),
("VTOP", "顶端值"),
("VBASe", "底端值"),
("VAMP", "幅度"),
("AVERage", "平均值"),
("SQUAresum", "均方根值"),
("CYCRms", "周期均方根"),
("PERiod", "周期"),
("FREQuency", "频率"),
("RTime", "上升时间"),
("FTime", "下降时间"),
]
for item, desc in items:
resp = send(f':MEASUrement:CH2:{item}?')
text = resp.decode('ascii', 'ignore').strip() if resp else "(无响应)"
print(f" CH2:{item:<12s} → {text!r} ({desc})")
# ═══════════════════════════════════════════════════════════════════
# 5. :MEASUrement:CH2? — 全部测量项 (JSON)
# ═══════════════════════════════════════════════════════════════════
section("5. :MEASUrement:CH2? — CH2 全部测量项 (JSON)")
resp = send(':MEASUrement:CH2?')
print(f" 原始字节长度: {len(resp)}")
text = resp.decode('ascii', 'ignore') if resp else "(无响应)"
# 可能含 4 字节前缀
if len(resp) >= 4:
pre_len = struct.unpack('<I', resp[:4])[0]
if pre_len + 4 == len(resp):
print(f" → 检测到 4 字节长度前缀: 声明 {pre_len}, 实际载荷 {len(resp)-4}")
text = resp[4:].decode('ascii', 'ignore')
else:
print(f" → 前 4 字节 = {pre_len}, 总长 = {len(resp)}, 不匹配前缀格式")
print(f"\n 原始文本:")
print(f" {text[:800]}")
try:
parsed = json.loads(text.strip())
print(f"\n JSON 解析成功! Keys: {list(parsed.keys())}")
for k, v in parsed.items():
print(f" {k}: {v}")
except json.JSONDecodeError:
print(f"\n JSON 解析失败,尝试找 {...}")
# 尝试只提取 JSON 部分
i = text.find('{')
j = text.rfind('}')
if i >= 0 and j > i:
try:
sub = text[i:j+1]
parsed = json.loads(sub)
print(f" 截取 JSON 成功! [{i}:{j+1}] Keys: {list(parsed.keys())}")
for k, v in parsed.items():
print(f" {k}: {v}")
except Exception as e:
print(f" 截取 JSON 也失败: {e}")
# ═══════════════════════════════════════════════════════════════════
# 6. 运行状态查询
# ═══════════════════════════════════════════════════════════════════
section("6. 运行状态 & 其他查询")
for cmd in [':RUNning?', ':TRIGger:STATUS?', ':TRIGger:TYPE?',
':ACQuire:MODE?', ':ACQuire:DEPMEM?',
':HORIZONTAL:SCALe?', ':CH2:SCALe?', ':CH2:PROBe?',
':CH2:COUPling?', ':CH2:OFFSET?']:
resp = send(cmd)
text = resp.decode('ascii', 'ignore').strip() if resp else "(无响应)"
print(f" {cmd:<30s} → {text!r}")
# ═══════════════════════════════════════════════════════════════════
# 7. BMP 大小检查
# ═══════════════════════════════════════════════════════════════════
section("7. :DATA:WAVE:SCREen:BMP? — BMP 大小")
resp = send(':DATA:WAVE:SCREen:BMP?', timeout=15000)
print(f" 原始字节总长度: {len(resp)}")
if len(resp) >= 4:
declared = struct.unpack('<I', resp[:4])[0]
print(f" 声明 BMP 大小: {declared} ({declared/1024:.1f} KB)")
if len(resp) - 4 == declared:
print(f" ✓ 长度匹配")
# BMP 头检查
bmp = resp[4:]
if bmp[:2] == b'BM':
bmp_size = struct.unpack('<I', bmp[2:6])[0]
print(f" BMP 内部声明大小: {bmp_size}")
width = struct.unpack('<i', bmp[18:22])[0]
height = struct.unpack('<i', bmp[22:26])[0]
print(f" 分辨率: {width} x {height}")
else:
print(f" ✗ 长度不匹配: +{len(resp)-4} vs {declared}")
# ═══════════════════════════════════════════════════════════════════
# 8. :DATA:WAVE:DEPMem:All? — 深存储
# ═══════════════════════════════════════════════════════════════════
section("8. :DATA:WAVE:DEPMem:All? — 深存储 (超时可能较长)")
resp = send(':DATA:WAVE:DEPMem:All?', timeout=30000)
print(f" 原始字节总长度: {len(resp)}")
if len(resp) >= 4:
declared = struct.unpack('<I', resp[:4])[0]
print(f" 声明大小: {declared} ({declared/1024:.1f} KB)")
print(f" 实际载荷: {len(resp)-4}, 匹配: {declared == len(resp)-4}")
print(f" 原始 hex (前 80): {resp[:80].hex()}")
# ═══════════════════════════════════════════════════════════════════
# 9. CH1 波形数据对比
# ═══════════════════════════════════════════════════════════════════
section("9. :DATA:WAVE:SCREen:CH1? — CH1 波形 (对比)")
resp = send(':DATA:WAVE:SCREen:CH1?')
print(f" 原始字节总长度: {len(resp)}")
if len(resp) >= 4:
declared = struct.unpack('<I', resp[:4])[0]
print(f" 前缀声明: {declared}, 载荷: {len(resp)-4}, 匹配: {declared == len(resp)-4}")
payload = resp[4:]
if len(payload) >= 6:
raw = struct.unpack(f'<{len(payload)//2}H', payload)
raw = [v & 0x0FFF for v in raw]
print(f" 点数: {len(raw)}, ADC 范围: [{min(raw)}, {max(raw)}]")
print(f" 前 10: {raw[:10]}")
print(f" 后 10: {raw[-10:]}")
# ═══════════════════════════════════════════════════════════════════
# 10. CH1 各项测量值
# ═══════════════════════════════════════════════════════════════════
section("10. :MEASUrement:CH1 各项")
for item, desc in items[:8]: # 只测第一部分
resp = send(f':MEASUrement:CH1:{item}?')
text = resp.decode('ascii', 'ignore').strip() if resp else "(无响应)"
print(f" CH1:{item:<12s} → {text!r}")
# ═══════════════════════════════════════════════════════════════════
# 11. :MEASUrement:ALL? — 两通道全部测量
# ═══════════════════════════════════════════════════════════════════
section("11. :MEASUrement:ALL? — 全部通道测量")
resp = send(':MEASUrement:ALL?')
print(f" 原始字节长度: {len(resp)}")
if len(resp) >= 4:
pre_len = struct.unpack('<I', resp[:4])[0]
if pre_len + 4 <= len(resp):
payload = resp[4:4+pre_len]
text = payload.decode('ascii', 'replace')
print(f" 载荷 ({len(payload)} bytes):")
print(f" {text[:1000]}")
else:
print(f" 前缀声明 {pre_len} > 数据长 {len(resp)-4}")
# ═══════════════════════════════════════════════════════════════════
# 12. 连续读取 CH2 数据 5 次,看 md5 是否变化
# ═══════════════════════════════════════════════════════════════════
section("12. 连续读取 CH2 × 5 — 验证数据刷新")
prev = None
for i in range(5):
resp = send(':DATA:WAVE:SCREen:CH2?')
h = hashlib.md5(resp).hexdigest()[:8] if resp else "None"
changed = ""
if prev is not None:
changed = "★ 变化" if h != prev else " (不变)"
print(f" [{i+1}] {len(resp)}B md5={h} {changed}")
prev = h
if i < 4:
time.sleep(0.05)
# ═══════════════════════════════════════════════════════════════════
# 13. 测试 :RUNning RUN 后是否刷新数据
# ═══════════════════════════════════════════════════════════════════
section("13. :RUNning RUN 后刷新测试")
base = send(':DATA:WAVE:SCREen:CH2?')
base_md5 = hashlib.md5(base).hexdigest()[:8] if base else "None"
print(f" 基准: {len(base)}B md5={base_md5}")
for i in range(3):
send(':RUNning STOP')
time.sleep(0.2)
send(':RUNning RUN')
time.sleep(0.5)
resp = send(':DATA:WAVE:SCREen:CH2?')
h = hashlib.md5(resp).hexdigest()[:8] if resp else "None"
changed = "★ 变化" if h != base_md5 else " (不变)"
print(f" STOP+RUN [{i+1}]: {len(resp)}B md5={h} {changed}")
# ═══════════════════════════════════════════════════════════════════
# 14. 强制单次触发后读波形数据
# ═══════════════════════════════════════════════════════════════════
section("14. :TRIGger:SINGLE 强制触发后读波形")
print(" 先 STOP,再 SINGLE,然后读数据...")
send(':RUNning STOP')
time.sleep(0.3)
for i in range(5):
send(':TRIGger:SINGLE')
time.sleep(1.5) # 等待触发完成 (时基 10us * 10div = 100us, 但实际需要采集+传输)
# 检查触发状态
status = send(':TRIGger:STATUS?')
resp = send(':DATA:WAVE:SCREen:CH2?')
h = hashlib.md5(resp).hexdigest()[:8] if resp else "None"
status_text = status.decode('ascii','ignore').strip() if status else "?"
print(f" [{i+1}] 状态={status_text} {len(resp)}B md5={h}")
# ═══════════════════════════════════════════════════════════════════
# 15. RUN 模式下读 CH2 + 同时读测量值看是否同步变化
# ═══════════════════════════════════════════════════════════════════
section("15. RUN 模式下对比测量值和波形 md5")
send(':RUNning RUN')
time.sleep(0.5)
prev_wave_md5 = None
for i in range(5):
wave = send(':DATA:WAVE:SCREen:CH2?')
pkpk = send(':MEASUrement:CH2:PKPK?')
wave_md5 = hashlib.md5(wave).hexdigest()[:8] if wave else "None"
pkpk_text = pkpk.decode('ascii','ignore').strip() if pkpk else "?"
wave_changed = ""
if prev_wave_md5 is not None:
wave_changed = "★波形变化" if wave_md5 != prev_wave_md5 else ""
print(f" [{i+1}] PKPK={pkpk_text} 波形 md5={wave_md5} {wave_changed}")
prev_wave_md5 = wave_md5
time.sleep(0.5)
# ═══════════════════════════════════════════════════════════════════
# 16. 测试 :MEASUrement:CH2? JSON 净化解析
# ═══════════════════════════════════════════════════════════════════
section("16. :MEASUrement:CH2? JSON 净化后解析")
resp = send(':MEASUrement:CH2?')
if len(resp) >= 4:
pre_len = struct.unpack('<I', resp[:4])[0]
if pre_len + 4 <= len(resp):
raw_text = resp[4:4+pre_len].decode('ascii', errors='replace')
# 替换 tab 字符
clean = raw_text.replace('\t', '')
print(f" 净化后文本前 300 字符:")
print(f" {clean[:300]}")
try:
parsed = json.loads(clean)
ch2 = parsed.get("CH2", {})
print(f"\n 解析成功! 有效值:")
for k, v in ch2.items():
v_clean = v.rstrip('?').rstrip(',').rstrip(',OFF').rstrip(',ON')
if v_clean and v_clean != '' and v_clean != ' ':
print(f" {k}: {v} → clean={v_clean}")
except json.JSONDecodeError as e:
print(f" 净化后仍失败: {e}")
# 尝试更激进净化
clean2 = ''.join(c for c in raw_text if c.isprintable() or c in '{}":,.[]')
try:
parsed = json.loads(clean2)
print(f" 激进净化后解析成功!")
except:
print(f" 激进净化也失败")
section("调研完成")
usb.util.dispose_resources(dev)

1059
backend/uv.lock 自动生成的

文件差异内容过多而无法显示 加载差异

查看文件

@ -164,6 +164,12 @@ const handleContinue = () => {
} }
} }
const handleReset = async () => {
if (!confirm('确定要重置实验数据吗?所有已填数据将被清除。')) return
await experimentStore.resetAndRestart()
allValidated.value = false
}
const handleExport = async () => { const handleExport = async () => {
if (!canExport.value || exporting.value) return if (!canExport.value || exporting.value) return
exporting.value = true exporting.value = true
@ -245,6 +251,12 @@ watch(
> >
{{ continueButtonText }} {{ continueButtonText }}
</button> </button>
<button
class="reset-button"
@click="handleReset"
>
重置
</button>
<button <button
v-if="canExport" v-if="canExport"
class="export-button" class="export-button"
@ -466,6 +478,20 @@ watch(
.continue-button:hover:not(:disabled) { background: #218838; } .continue-button:hover:not(:disabled) { background: #218838; }
.reset-button {
padding: 0.6rem 1.25rem;
border-radius: 4px;
border: 1px solid #dc3545;
background-color: #fff;
color: #dc3545;
font-weight: 600;
font-size: 0.9rem;
cursor: pointer;
transition: all 0.2s ease;
}
.reset-button:hover { background-color: #fff5f5; }
.export-button { .export-button {
padding: 0.6rem 1.25rem; padding: 0.6rem 1.25rem;
border-radius: 4px; border-radius: 4px;

查看文件

@ -321,6 +321,31 @@ export const useExperimentStore = defineStore('experiment', () => {
allAreas.forEach((areaId) => calculateArea(areaId)) allAreas.forEach((areaId) => calculateArea(areaId))
} }
const resetAndRestart = async () => {
if (!config.value) return
const savedConfig = config.value
const savedValidationUrl = validationUrl.value
if (savedValidationUrl) {
try {
const response = await fetch(savedValidationUrl.replace(/\/$/, '') + '/reset', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
})
if (response.ok) {
const result = await response.json()
pendingField.value = result.pending_field || null
controlStatus.value = result.control_status || null
}
} catch (e) {
console.error('重置后端失败:', e)
}
}
setConfig(savedConfig, savedValidationUrl || undefined)
}
const resetExperiment = () => { const resetExperiment = () => {
config.value = null config.value = null
data.value = {} data.value = {}
@ -377,6 +402,7 @@ export const useExperimentStore = defineStore('experiment', () => {
setFieldValue, setFieldValue,
validateField, validateField,
updateAreaCalculations, updateAreaCalculations,
resetAndRestart,
resetExperiment, resetExperiment,
loadConfigFromUrl, loadConfigFromUrl,
findInputCell, findInputCell,

960
流程框图设计prompt.md 普通文件
查看文件

@ -0,0 +1,960 @@
# AI + 声速测量实验 —— 流程框图设计 Prompt
> **全局约束**:所有图均为 **单张 1920×1080 横版 PPT 页面**,中文文字直接渲染,非插图素材。继承统一视觉规范(深海蓝 `#0B1E3D` 主色调、金色 `#F59E0B` 强调、浅灰 `#F0F4F8` 背景、顶部 80px 深蓝标题栏、左上角页号蓝点、底部 2px 深蓝细线)。流程图使用圆角矩形节点 + 渐变色箭头 + 统一图标集。
---
## 图 1:学生实验全流程 —— 从登录到总结
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:学生实验全流程 —— 从登录到总结
【流程主体 — 横向五阶段主流程(占高 35%)】
五个大型圆角矩形阶段节点等距横向排列,箭头连接。每个节点包含:
- 顶部插图图标
- 阶段名称(白色粗体 18pt,节点彩色背景)
- 阶段说明(白色 12pt 小字)
节点一(蓝绿色 #10B981 背景):
图标:书本 + 播放按钮
名称:预习阶段 (LearnPage)
说明:观看教学视频 + AI 助教 SSE 流式对话
节点二(橙色 #EA580C 背景):
图标:试卷 + 对勾
名称:测验阶段 (QuizPage)
说明:作答选择题/填空题 + AI 智能批改诊断
节点三(紫色 #7C3AED 背景):
图标:表格 + 示波器波形
名称:实验阶段 (ExperimentPage)
说明:数据记录 + 硬件采集 + AI 实时评价 + 级联计算 + PDF 导出
节点四(蓝色 #2563EB 背景):
图标:试卷 + 时钟
名称:考试阶段 (ExamPage)
说明:限时考核
节点五(金色 #F59E0B 背景):
图标:文档 + 对勾
名称:总结阶段 (ReportPage)
说明:实验报告 + 成绩汇总
【流程上方 — 路由导航层(占高 15%)】
顶部淡蓝色横向条带,展示 SPA 路由跳转:
/login → (登录守卫检查 localStorage) → /select → (选择实验卡片) → /exp?expid=...
路由下方标注组件名:StudentLogin → ExperienceSwitch → ExperienceFrame(主框架,驱动阶段切换)
【流程下方 — Pinia Store 数据流层(占高 25%)】
两个大型浅色卡片并排:
左侧卡片(useStudentStore):
- 标题:学生状态管理
- 内容:doLogin(Name, SID) → localStorage 持久化 → router.beforeEach 每次鉴权
右侧卡片(useExperimentStore):
- 标题:实验数据管理
- 子项(纵向排列):
setConfig(json) → 初始化 fieldData + areaResults
setFieldValue(id, val) → 标记未验证 → 清除依赖 + 触发级联重算
validateField(id) → POST /value → 更新验证状态
updateAreaCalculations() → 递归依赖图 → 级联求值
【右侧伴随 — AI 角色映射列(占宽 12%)】
三个竖向排列的小节点,用侧线连接到主流程对应阶段:
预习 ←→ 智能助教 (question · SSE 流式)
实验 ←→ 数据评价官 (data_eval · 悬停触发)
测验 ←→ 智能批卷官 (grader · 提交后触发)
【底部关系线】主流程下方虚线标注:「阶段导航由 ExperienceFrame 的 Process 索引控制 · 支持 keep-alive 缓存」
```
---
## 图 2:实验数据完整生命周期
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:实验数据完整生命周期
【主体 — 循环数据流(占高 80%)】
采用环形/螺旋布局,从左上开始顺时针排列 7 个阶段节点,节点间用渐变色箭头连接(蓝→紫→金)。
节点一(左上,蓝色):加载配置
图标:JSON 花括号 + 文件夹
内容:
前端 GET /form?experiment=voice_speed
→ 后端 ExperimentConfigService.load_validated()
→ 返回 ExperimentGridConfig (7 Sheets, ~80 cells)
→ 前端 store.setConfig() 初始化 fieldData + areaResults
节点二(上中,青色):渲染界面
图标:浏览器窗口 + 表格
内容:
ExperimentForm provide AIEvalContext
→ ExperimentGrid × N(每个 Sheet 一个网格)
→ ExperimentGridCell(label/input/computed)
→ LaTeX 标签 + 输入框 + 计算显示区
节点三(右上,紫色):用户输入
图标:键盘 + 鼠标光标
内容:
用户在 input 单元格输入数据
→ @input 触发 store.setFieldValue(fieldId, value)
→ 标记 validated=false → 清除该字段所有依赖区的计算结果
→ 触发 store.updateAreaCalculations() 级联重算
→ 单元格背景变为黄色(#FFF3CD 待验证)
节点四(右中,红色):后端验证
图标:对勾 + 盾牌
内容:
@blur 触发 store.validateField(fieldId)
→ POST /value { field_id, value }
→ FieldValidator.validate_by_config()
· 类型校验(number/text/regex)
· 范围校验(min/max)
· 必填校验(required)
→ ReadingGuardManager.validate()
· 读数顺序检查(strict_fields cursor)
· 硬件参考值对比(双级容差)
· peak_ocr 源自动触发峰值监控
→ SessionStore.set_value()
→ 返回 { accept, message, severity }
节点五(右下,绿色):验证反馈
图标:调色板 + 状态灯
内容:
前端接收 FieldValidationResponse
→ 更新 data.value[fieldId].validationResult
→ 更新 validated=true
→ 更新 pendingField / controlStatus
→ 根据 accept 更新单元格背景色:
· 绿色 #D4EDDA = 通过
· 红色 #F8D7DA = 失败
→ 若 accept=true → 再次触发 updateAreaCalculations()
节点六(下中,金色):级联计算
图标:齿轮 + 箭头网络
内容:
updateAreaCalculations() 递归遍历所有 computed 区
→ 对每个 areaId:
· 查找 GridComputedCell 定义
· 收集 variables(从 fieldData 或 areaResults)
· 若依赖的计算区未求值 → 递归计算
· calculateExpression() → LaTeX 转 mathjs 求值
· formatNumber() → 格式化输出
· 若结果变化 → 触发该区的依赖者继续级联
→ 循环引用检测:visitedAreas Set
节点七(左下,紫色):AI 评价
图标:AI 芯片 + 对话气泡
内容:
鼠标悬停已填写单元格 600ms
→ aiContext.requestEvaluation(focus)
→ POST /api/chat (teacherType=data_eval)
→ 携带完整上下文:configSummary + fieldData + areaResults + studentInfo
→ AI 返回结构化 JSON
→ 渲染评价气泡:等级/误差/数据质量/点评/建议
【中央环形中心】一个圆形芯片图标标注「dataVersion 递增驱动全链路联动」
【底部信息条】color-coded 循环箭头标注:输入 → 验证 → 计算 → 评价 → 反馈 → 输入(教学闭环)
```
---
## 图 3:字段验证完整流程 —— POST /value 前后端协同
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:字段验证完整流程 —— POST /value 前后端协同
【采用左右泳道布局,左侧蓝色泳道 "前端 Vue 3",右侧绿色泳道 "后端 FastAPI"】
【左侧泳道 — 前端流程(占宽 48%)】
步骤(自上而下排列,纵向箭头连接):
步骤 1:用户失焦 (@blur)
插图:input 单元格高亮,光标离开
文字:用户输入完成,焦点离开单元格
步骤 2:store.validateField(fieldId)
插图:函数调用流程图
文字:从 data[fieldId] 取 value,检查 validationUrl 是否存在
步骤 3:构造请求
插图:HTTP POST 图标
文字:POST validationUrl
Headers: Content-Type: application/json
Body: { field_id: "s_l0", value: 144.02 }
步骤 4:等待响应
插图:loading spinner
文字:await fetch() · 异步等待
【泳道间大箭头】标注「REST API · JSON 序列化」
【右侧泳道 — 后端流程(占宽 48%)】
步骤 5:路由接收
插图:FastAPI 路由图标
文字:POST /value?experiment=voice_speed · api/value.py
步骤 6:查找字段定义
插图:搜索放大镜 + JSON 树
文字:find_field(experiment, field_id)
遍历所有 Sheet → 所有行 → 所有列 → 匹配 fieldId
返回 GridInputCell(含 validation、readingGuard 配置)
步骤 7:基础校验 (FieldValidator)
插图:规则列表
文字:validate_by_config(config, value)
├─ config == null → 直接通过
├─ required && empty → 拒绝 "必填项"
├─ type == number → float(value) → min/max 检查
├─ type == regex → re.fullmatch(pattern, value)
└─ 默认 → 通过
步骤 8:读数守卫校验 (ReadingGuardManager)
插图:盾牌 + 顺序箭头 + 容差标尺
文字:_ensure_initialized() → 构建 strict_fields 列表
validate(field_id, value)
├─ cursor 检查顺序(必须按 strict_fields 顺序)
├─ 获取参考值(manual / device_frequency / peak_ocr)
├─ 双级容差比对:
│ |value - 参考值| ≤ tolerance1 → 通过(绿色)
│ |value - 参考值| ≤ tolerance2 → 警告通过(黄色)
│ |value - 参考值| > tolerance2 → 拒绝(红色)
├─ peak_ocr 源 → 自动启动峰值监控 + OCR 读数
└─ 更新 cursor + pending_field
步骤 9:存储 + 响应
插图:内存/数据库图标 + 返回箭头
文字:SessionStore.set_value(session_id, field_id, value)
返回 { accept: true/false, message, severity, reference, pending_field, control_status }
【底部横向条带 — 验证结果颜色映射(贯穿两泳道)】
四个颜色方块横排,箭头指向前端单元格渲染:
⬜ #FFFFFF 未填写 | 🟦 #E8F0FE 获焦 | 🟨 #FFF3CD 待验证 | 🟩 #D4EDDA 通过 | 🟥 #F8D7DA 失败
【右侧标注】虚线框标注「前后端类型对齐」:
前端 TypeScript FieldValidationResponse ↔ 后端 Pydantic FieldValidationResponse(camelCase)
```
---
## 图 4:峰值检测状态机 —— PeakDetector
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:峰值检测状态机 —— 四态自动循环
【左侧(占宽 55%)— 状态机核心流转图】
四个大型圆形状态节点,用带条件的箭头连接形成循环。每个节点含:
- 状态名(粗体 16pt,节点填充色)
- 状态描述(12pt)
- 节点内插图
状态一(顶部偏左,灰色 #9CA3AF):IDLE
插图:待机图标(圆圈+横线)
描述:初始化/未启动 · buffer 清空 · state 复位
进入条件:reset() / 系统启动
离开条件(箭头标注):buffer 满 window_size 个值 且 最新值 < 最早值×(1-0.05)
状态二(顶部偏右,蓝色 #3B82F6):RISING
插图:上升箭头 + 波形爬升
描述:跟踪上升趋势 · 持续更新 peak_max = max(buffer)
逻辑:当前值 > peak_max → 更新 peak_max
离开条件(箭头标注):当前值 < peak_max × (1 - 0.05) → 下降超过 5%
状态三(底部偏右,金色 #F59E0B):PEAK_TRIGGERED
插图:星星 + 峰值标记点
描述:峰值已检测 · 等待学生确认 · peak_index++
伴随动作:CaliperOCRService 捕获游标卡尺读数 · 通知前端显示
离开条件(箭头标注):学生 acknowledge_peak() → 进入 COOLDOWN
状态四(底部偏左,紫色 #7C3AED):COOLDOWN
插图:冷却温度计图标
描述:确认后冷却期 · 清空 buffer + ocr_reading · buffer 重置
逻辑:等待值充分下降(低于 valley)后再上升
离开条件(箭头标注):当前值 > valley×(1+0.05×2) → 重新进入 IDLE
【右侧(占宽 40%)— 辅助说明区】
上部卡片 — 关键参数:
drop_ratio = 0.05(下降 5% 触发峰值)
cooldown_ratio = 0.30(冷却至峰值的 70% 以下)
window_size = 5(滑动窗口大小)
polling_interval = 0.3s(后台线程轮询间隔)
中部卡片 — feed() 方法逻辑:
伪代码面板(深蓝背景,白字):
buffer.append(value)
if state==IDLE and buffer满 and 下降触发 → 保持IDLE
if state==RISING and value下降>5% → PEAK_TRIGGERED
if state==PEAK_TRIGGERED → 等待acknowledge
if state==COOLDOWN and value再上升 → IDLE
下部卡片 — 与硬件/前端的交互:
示波器 CH2 峰值 → 0.3s 轮询 → feed(peak_value)
PEAK_TRIGGERED → OCR 读数 → 通知前端 pending_field
学生确认 → POST /peak-monitor/acknowledge → acknowledge_peak()
【底部 — 时间轴波形示意】一个简化的波形曲线图,标注四个状态切换点(IDLE→RISING→PEAK→COOLDOWN→IDLE)
```
---
## 图 5:读数守卫流程 —— ReadingGuardManager
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:读数守卫 ReadingGuardManager 校验流程
【主体 — 自上而下决策树(占高 75%)】
采用自上而下的决策树/泳道布局,菱形=判断,矩形=动作。
层级一(顶部):初始化
节点(蓝色矩形):_ensure_initialized(session_id, experiment_config)
说明:遍历所有 Sheet → cells → input → readingGuard.enabled==true
构建 strict_fields[] 有序列表 + cursor=0 + 武装第一个 pending_field
层级二:校验入口
节点(青色矩形):validate(session_id, field_id, student_value)
说明:学生提交 POST /value 后调用
层级三:顺序检查(菱形判断)
插图:顺序箭头图标
判断:field_id 是否在 strict_fields 中?
├─ 否(右分支,灰色)→ 跳过守卫,只做基础验证 → 返回 accept:true
└─ 是(下分支)→ 继续
层级四:顺序检查(菱形判断)
判断:field_id 是否等于 strict_fields[cursor](期望的下一个字段)?
├─ 否(右分支,红色)→ 拒绝:提醒先填写 pending_field
└─ 是(下分支)→ 继续
层级五:获取参考值(矩形分支,根据 source 分三路)
左路(manual):手动答案 → state.manual_answers[field_id]
中路(device_frequency/device_peak):oscilloscope_service.capture_xxx() → 硬件实时读取
右路(peak_ocr):自动启动峰值监控 → 等待 OCR 读数 → 返回参考值
层级六:双级容差比对(菱形+矩形组合)
插图:容差标尺(绿色区域 → 黄色区域 → 红色区域)
计算:delta = |student_value - reference_value|
判断一:delta ≤ tolerance1?
├─ 是 → accept:true, severity:"pass"(绿色)
└─ 否 → 继续
判断二:delta ≤ tolerance2?
├─ 是 → accept:true, severity:"warning"(黄色)· 提示数据偏差但可接受
└─ 否 → accept:false(红色)· 拒绝并要求重新读数
层级七(底部):状态更新
节点(绿色矩形):更新状态
内容:
if accept:
cursor += 1
if cursor < len(strict_fields):
pending_field = strict_fields[cursor] ← 武装下一个字段
else:
pending_field = null ← 所有守卫字段完成
return { accept, message, severity, reference, pending_field }
【右侧浮层 — 不同 source 的说明卡片】
卡片一(manual 源):
图标:教师头像图标
说明:教师通过 POST /device/manual-answer 手动设置参考值
用于无硬件环境下的模拟教学
卡片二(device_frequency/device_peak 源):
图标:示波器探头图标
说明:实时从示波器采集 CH1 频率 / CH2 峰值作为参考值
容差 = 频率 0.5kHz / 距离 0.05mm
卡片三(peak_ocr 源):
图标:摄像头+游标卡尺图标
说明:触发峰值检测 → 峰值确认时 OCR 读取游标卡尺值
容差 = 0.05mm(严格)/ 0.1mm(容忍)
【底部信息条】undo() 支持:学生可撤回上一次读数 → cursor -= 1 → 重新武装上一个 pending_field
```
---
## 图 6:级联计算递归流程 —— updateAreaCalculations
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:级联计算引擎 —— updateAreaCalculations() 递归依赖图解析
【左侧(占宽 45%)— 单个计算区的求值流程】
自上而下垂直流程,6 个圆角矩形节点:
步骤 1(蓝色):calculateArea(areaId) 入口
检查:visitedAreas.has(areaId)? → 是则返回 false(循环引用检测)
否则 visitedAreas.add(areaId)
步骤 2(青色):查找计算定义
调用 findComputedCell(areaId) → 获取 GridComputedCell
包含:expression(LaTeX 公式)、variables[](依赖列表)、format(输出格式)
步骤 3(紫色):解析依赖变量
遍历 variables[],对每个 varId:
├─ 存在于 data[varId] 且 validated=true → 直接取值
├─ 存在于 areaResults[varId] 且 value≠null → 直接取值
├─ 存在 findComputedCell(varId)(是计算区)→ 递归 calculateArea(varId)
│ └─ 递归返回后检查 updatedResult.value ≠ null → 取值
└─ 不存在 → allVarsReady=false
步骤 4(红色判断菱形):allVarsReady?
├─ 否 → 设置 areaResults[areaId] = { value:null, formatted:"等待输入..." }
└─ 是 → 继续
步骤 5(金色):表达式求值
调用 calculateExpression(expression, variables)
→ convertLatexToMathJS() 转换 LaTeX → mathjs
→ math.compile() 编译表达式树
→ compiled.evaluate(variables) 代入变量求值
→ formatNumber(result, format) 格式化输出
步骤 6(绿色):级联传播
若计算结果变化 → 调用 getDependentAreas(areaId)
遍历依赖者列表 → 对每个未访问的依赖者递归 calculateArea()
【右侧(占宽 50%)— 声速实验依赖图实例】
一张实际的声速实验 DAG(有向无环图),节点用彩色椭圆/矩形:
输入层(蓝色):
f1 f2 f3 f4 f5 温度 s_l0~s_l9 p_l0~p_l9 t_l1~t_l10 t_t1~t_t10
中间计算层(紫色):
frequency_avg v₀理论值 s_d1~s_d5 p_d1~p_d5 t_dl1~t_dl5 t_dt1~t_dt5
s_d_avg p_d_avg t_dl_avg t_dt_avg
关键中间量层(金色):
lambda_standing lambda_phase
最终结果层(红色):
v_standing v_phase v_time
err_standing err_phase err_time
汇总层(绿色,连接三种方法):
cmp_v_standing cmp_err_standing cmp_v_phase cmp_err_phase cmp_v_time cmp_err_time
【依赖关系箭头】
- frequency_avg ← f1,f2,f3,f4,f5(5条箭头汇聚)
- v₀ ← 温度
- s_d1 ← s_l5, s_l0(配对差)
- s_d_avg ← s_d1~s_d5(5条汇聚)
- lambda_standing ← s_d_avg
- v_standing ← frequency_avg, lambda_standing(2条汇聚)
- err_standing ← v_standing, v₀(2条汇聚)
- cmp_v_standing ← v_standing(跨表引用)
【底部说明条】
用虚线框圈出"输入 s_l3 变化的影响传播范围":
s_l3 → s_d3, s_d4 → s_d_avg → lambda_standing → v_standing, err_standing → cmp_v_standing, cmp_err_standing
共 7 个节点级联重算(仅占 40+ 计算区的 17.5% → 增量更新效率高)
标注文字:「getAllDependentAreas() 通过 BFS 获取传递闭包 · visitedAreas Set 防止循环引用」
```
---
## 图 7:AI 多角色评价触发流程
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:AI 多角色评价 —— 三种 teacherType 的触发与响应流程
【顶部(占高 15%)— AI 服务概览】
三个横向排列的 AI 角色概要卡片(小尺寸),与下方详图做映射:
卡片一(青绿):question · 智能助教 · SSE 流式
卡片二(紫色):data_eval · 数据评价官 · REST 单次
卡片三(橙色):grader · 智能批卷官 · REST 单次
【主体 — 三条并行泳道(各占宽 30%)】
====== 泳道一:智能助教 (question) ======
触发流程(纵向自上而下):
1. 用户打开预习页 (LearnPage)
2. 加载 prelearn.json 内容 → 截取前 2000 字符作为 context
3. 用户输入问题 → AIChatSidebar 接收
4. 构造 ChatMessage[]: [{role:"system", content:context}, {role:"user", content:question}]
5. 调用 streamChat({ teacherType:'question', messages, stream:true })
6. SSE 连接建立 → 逐 token 接收 → onToken() 实时渲染
7. 响应完成后 extractJsonBlock() 提取结构化 JSON
8. 按分层模板渲染:
- 核心概念 (core_concept)
- 直接回答 (direct_answer)
- 理解提示 (understanding)
- 深入说明 (deep_dive)
- 实验提示 (practical_tips)
- 自检问题 (self_check_questions)
通信方式标注:SSE 流式 · 实时逐字显示
====== 泳道二:数据评价官 (data_eval) ======
触发流程:
1. 鼠标悬停在已填写单元格上,启动 600ms 定时器
2. 定时器到 → 检查 dataVersion 缓存(避免重复请求)
3. 构造 AIEvalFocus: { type:'field', id, label, value, unit }
4. 调用 aiContext.requestEvaluation(focus)
5. ExperimentForm.requestEvaluation() 收集完整快照:
- configSummary(所有 fields 定义 + areas 定义)
- fieldData(所有字段的当前值)
- areaResults(所有计算的当前结果)
- studentInfo(学生姓名+学号)
6. 构造 ChatMessage[]:
[{role:"system", content:"你是实验数据评价专家..."},
{role:"user", content: JSON.stringify({ context, focus })}]
7. 调用 chatOnce({ teacherType:'data_eval', messages, stream:false })
8. 解析返回 JSON → 渲染评价气泡:
- 等级评定 + 等级说明 (grade + grade_description)
- 相对误差百分比 (relative_error_percent)
- 数据质量评估 (data_quality_assessment)
- 教师评语 (teacher_comments)
- 改进建议 (improvement_suggestions)
通信方式标注:REST 单次 · 悬停 600ms 防抖
====== 泳道三:智能批卷官 (grader) ======
触发流程:
1. 学生完成测验 → 提交答案
2. QuizPage 收集错题信息(题目+学生答案+标准答案)
3. 构造 ChatMessage[]:
[{role:"system", content:"你是物理实验评分专家..."},
{role:"user", content: JSON.stringify(wrongAnswers)}]
4. 调用 chatOnce({ teacherType:'grader', messages, stream:false })
5. 解析返回 JSON → AnswerSummary 渲染:
- 正确性反馈 (correctness_feedback)
- 错误诊断 (diagnosis)
- 错误解释 (error_explanation)
- 知识点评估 (knowledge_points_evaluated)
- 改进建议 (improvement_suggestions)
- 拓展问题 (extension_questions)
通信方式标注:REST 单次 · 提交后自动触发
【底部横条 — AI Client 公共层(贯穿三泳道)】
aiClient.ts 公共逻辑:
resolveBaseUrl() → /config.json → AIProvider.entrypoint
→ buildEndpoint() → {baseUrl}/api/chat
→ 请求体格式:{ teacher_type, messages, stream }
→ 日志记录:aiLogs[] (最多 100 条,DebugPanel 可查看)
→ SSE 格式:data: {"choices":[{"delta":{"content":"..."}}]}
→ JSON 提取:extractJsonBlock() 支持 ```json 和裸 {}
```
---
## 图 8:示波器硬件通信流程
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:示波器硬件通信流程 —— PyUSB SCPI 协议
【主体 — 从左到右管道布局(占高 65%)】
七个节点等距横向排列,粗箭头连接。节点上方标注层级归属(应用层/服务层/协议层/硬件层)。
节点一(应用层,最左,蓝色):API 调用
矩形标注:GET /device/status 或 POST /device/peak
子项:路由 layer → api/device.py → oscilloscope_service.xxx()
节点二(服务层,青色):OscilloscopeService
矩形标注:probe() / capture_peak() / capture_frequency()
子项:3 次重试机制(RETRY_COUNT=3, RETRY_DELAY=1.0s)
三层状态管理:ONLINE | OFFLINE | SIMULATED
节点三(协议层,紫色):SCPI 命令枚举
矩形标注:Commands enum(progress.py)
子项(代码风格):
IDN → "*IDN?"
MEASU_CH2 → ":MEASUrement:CH2:PKPK?"
MEASU_CH1_FREQ → ":MEASUrement:CH1:FREQuency?"
DATA_WAVE_CH2 → ":DATA:WAVE:SCREen:CH2?"
节点四(协议层,红色):命令执行器
矩形标注:ExecuteCmdInDev(device, command)
子项:device.write(command.encode()) + time.sleep(0.2)
device.read(4096) → _extract_numeric() 解析
节点五(驱动层,金色):Oscilloscope 类
矩形标注:PyUSB 底层驱动(oscilloscope.py)
子项:
- VID=0x5345, PID=0x1234(OWON NDS102U)
- Context manager (__enter__/__exit__)
- detach_kernel_driver()
- set_configuration()
- find bulk endpoints (IN/OUT)
节点六(硬件层,绿色):USB 总线
矩形标注:libusb / USB 物理连接
子项:数据包收发 · bulk transfer
节点七(硬件层,灰色):物理设备
插图:示波器正面板简图(OWON NDS102U)
子项:CH1 频率 · CH2 峰值电压
【分支 — 模拟回退路径(从节点二下方分出,橙色虚线箭头)】
节点二连接失败(3 次重试均失败)
→ 自动切换 HardwareStatus.SIMULATED
→ 返回 HardwareSnapshot(status=SIMULATED, note="示波器不可用,已切换为模拟模式")
→ 系统正常运行,无需物理硬件
分支上方标注:「自动回退机制 —— 开发/演示环境零硬件依赖」
【底部(占高 20%)— 启动探针流程时序图】
简化的时序泳道(水平时间线):
应用启动(main.py startup) → OscilloscopeService.probe()
→ 尝试连接 → 成功 → 缓存状态 ONLINE → 输出日志 "已连接真实示波器"
→ 或失败 → 重试(1) → 重试(2) → 重试(3) → 回退 SIMULATED → 输出日志
探针结果影响:
ReadingGuardManager source=device_frequency → 使用硬件实时频率
ReadingGuardManager source=peak_ocr → 使用模拟 OCR(预设 10 组距离值 + 随机噪声)
```
---
## 图 9:配置加载与前后端类型对齐
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:配置加载流程 + 前后端类型对齐机制
【左侧(占宽 48%)— 配置加载流程(自上而下)】
步骤一(蓝色):请求发起
插图:浏览器 + HTTP GET
内容:ExperimentPage 挂载 → store.loadConfigFromUrl(provider_url, validation_url)
fetch('http://localhost:8000/form?experiment=voice_speed')
步骤二(青色):后端路由
插图:FastAPI 图标 + 路由匹配
内容:GET /form?experiment=voice_speed → api/form.py
实验名默认值:cn.edu.muc.lxy.phyexp.voicespeed
步骤三(紫色):配置服务
插图:文件夹 + JSON 文件图标
内容:ExperimentConfigService(config_root)
_config_path(name) → config/experiments/{name}.json
load_raw(name) → json.loads(path.read_text())
load_validated(name) → ExperimentGridConfig(**raw_dict)
步骤四(红色):Pydantic 验证
插图:Pydantic 徽标 + 数据模型树
内容:ExperimentGridConfig 自动递归验证所有嵌套字段
├─ title: str
├─ description?: str
└─ sheets: List[GridSheet]
├─ id: str, columns: int
└─ cells: GridCell[][] → Union 判别
├─ GridLabelCell (type=="label")
├─ GridInputCell (type=="input")
└─ GridComputedCell (type=="computed")
验证失败 → HTTPException(500)
步骤五(金色):序列化返回
内容:config.model_dump(by_alias=True)
所有字段使用 camelCase(fieldId, areaId, colSpan)
→ JSON Response
步骤六(绿色):前端初始化
插图:Vue 组件树图标
内容:store.setConfig(json_config, validation_url)
→ 遍历所有 input cell → 初始化 data[fieldId]
→ 遍历所有 computed cell → 初始化 areaResults[areaId]
→ ExperimentForm 渲染 ExperimentGrid[] 组件
【右侧(占宽 48%)— 类型对齐机制】
上部 — 双向同步图:
左侧列(后端 Pydantic):schemas/experiment.py
右侧列(前端 TS):types/experiment.ts
中间双向箭头 + 锁图标标注「字段必须同步」
具体对齐示例表(深蓝背景,白字,等宽字体):
┌─────────────────────────────────────────────────────────┐
│ 后端 Pydantic (camelCase) │ 前端 TypeScript │
│─────────────────────────────────────────────────────────│
│ fieldId: str │ fieldId: string │
│ areaId: str │ areaId: string │
│ colSpan?: int │ colSpan?: number │
│ rowSpan?: int │ rowSpan?: number │
│ type: Literal["input"] │ type: 'input' │
│ validation?: ValidationConf │ validation?: Validation │
│ readingGuard?: ReadingGuard │ readingGuard?: Reading │
│ variables: List[str] │ variables: string[] │
└─────────────────────────────────────────────────────────┘
下部 — 序列化说明卡片:
后端 model_dump(by_alias=True) → JSON (camelCase)
→ HTTP 传输 → 前端 JSON.parse() → TypeScript interface
双向一致,无需手动映射
底部 — 图标标注:「新增字段必须同步修改两端 · 否则 Pydantic 验证失败 / TypeScript 类型检查报错」
```
---
## 图 10:PDF 导出流程 + 测验 AI 批改流程
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:PDF 实验报告导出 + 测验 AI 批改
【上半部(占高 55%)— PDF 导出流程,水平 7 步】
步骤 1(蓝色):用户点击导出
插图:下载按钮图标
内容:ExperimentPage 点击 "导出 PDF" 按钮
步骤 2(青色):定位导出元素
插图:DOM 树 + 选择器
内容:document.querySelector('[data-print-table]')
获取屏幕外隐藏的 ExperimentPrintTable DOM
步骤 3(紫色):html2canvas 截图
插图:DOM → 图片 转换图标
内容:html2canvas(element, {scale:2, useCORS:true, bg:'#ffffff'})
将 HTML 表格渲染为 Canvas,2x 缩放提高清晰度
步骤 4(红色):Canvas → PNG
插图:画布→文件图标
内容:canvas.toDataURL('image/png')
生成 Base64 编码的 PNG 图像数据
步骤 5(金色):jsPDF 初始化 + 布局计算
插图:PDF 文档 + 标尺
内容:new jsPDF({orientation:'portrait', unit:'mm', format:'a4'})
计算 img 缩放比例:contentWidth/imgWidth
autoScale 自动适配(minScale=0.75)
步骤 6(绿色):按页填充
插图:分页示意图
内容:pdf.addImage(imgData, x, position, w, h)
若表格超出一页 → 自动分页循环
while(heightLeft>0) { pdf.addPage(); addImage(); heightLeft-=contentHeight }
步骤 7(紫色):下载
插图:保存图标
内容:pdf.save(`${sheet.id}_${studentInfo.name}.pdf`)
支持多表格 → 多文件下载
【下半部(占高 35%)— 测验 AI 批改流程,水平 5 步】
步骤 1(蓝色):试题加载
插图:JSON 文件 + 试题列表
内容:QuizPage 加载 question.json
QuestionFileSchema 验证试题格式
QuestionTable 渲染多类型试题(单选/多选/填空/简答)
步骤 2(青色):学生作答
插图:笔 + 答卷
内容:学生逐题选择/填写答案
答案存储在本地 state
步骤 3(紫色):提交并收集错题
插图:对勾 + 错题收集箭头
内容:submit 触发 → 比对标准答案
收集:题目内容 + 学生答案 + 标准答案
步骤 4(红色):AI 批改
插图:AI 芯片 + 试卷图标
内容:chatOnce({teacherType:'grader', messages:[{role:'user', content:错题JSON}]})
返回结构化批改结果
步骤 5(金色):结果展示
插图:AnswerSummary 组件 + 卡片布局
内容:渲染正确答案反馈 + 错误诊断 + 知识点评估 + 改进建议 + 拓展问题
【中部贯穿标注】两段流程共享的公共模块:
useExperimentStore · aiClient.chatOnce() · html2canvas + jsPDF · KaTeX 渲染
```
---
## 图 11:Session 管理与会话隔离
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:多会话管理 —— SessionStore + X-Session-Id 隔离
【左侧(占宽 35%)— SessionStore 内部结构】
深蓝背景卡片,展示线程安全 KV 存储的数据结构:
SessionStore
├── _lock: threading.Lock(线程安全)
└── _data: Dict[str, Dict[str, FieldValue]]
├── "default"
│ ├── "f1" → { value: 36.540, validated: true }
│ ├── "s_l0" → { value: 144.02, validated: true }
│ └── ...
├── "session_abc123"
│ ├── "f1" → { value: 36.700, validated: false }
│ └── ...
└── "session_xyz789"
└── ...
方法:
get_value(session_id, field_id) → value
set_value(session_id, field_id, value)
get_all_values(session_id) → Dict[field_id, value]
delete_value(session_id, field_id)
clear_session(session_id)
clear_all()
【右侧(占宽 60%)— 会话隔离流程】
四个水平泳道(每个代表一个并发用户),展示并行请求处理:
泳道一(蓝色)— 学生 A (X-Session-Id: session_abc123):
POST /value {field_id:"f1", value:36.540}
→ find_field("voice_speed", "f1")
→ FieldValidator.validate_by_config()
→ reading_guard_manager.validate("session_abc123", "f1", 36.540)
→ session_store.set_value("session_abc123", "f1", 36.540)
→ 返回 accept:true
泳道二(绿色)— 学生 B (X-Session-Id: session_xyz789):
同时提交 POST /value {field_id:"f1", value:37.200}
→ 独立会话 · 互不干扰
→ reading_guard 独立 cursor
→ 返回 accept:false(超出频率范围)
泳道三(橙色)— 学生 A 继续 (X-Session-Id: session_abc123):
POST /value {field_id:"s_l0", value:144.02}
→ 读数守卫顺序检查通过(cursor 已推进到 s_l0)
→ 返回 accept:true
泳道四(灰色)— 无 Session 头 (default):
POST /value {field_id:"f1", value:36.540}
→ 使用 "default" 会话
→ 无 X-Session-Id 时的回退策略
【底部横条 — 会话隔离特点说明】
四个图标+文字并排:
🔒 线程安全(Lock) | 👥 多用户并发隔离 | 💾 纯内存存储(重启即清) | 🗑️ 支持单字段/整会话/全部清除(DELETE /value)
【右上角标注】虚线框:ReadingGuardManager、PeakDetector 同样按 session_id 隔离状态
```
---
## 图 12:新增实验步骤 —— 平台可扩展性证明
```
生成一张 1920×1080 横版 PPT 流程图。严格遵循全局风格锁。
标题栏文字:平台可扩展性 —— 新增实验仅需 JSON 配置
【主体 — 5 步横向流程 + 验证(占高 70%)】
步骤 1(蓝色):编写 JSON 配置
图标:代码编辑器 + JSON 文件
内容:在 backend/config/experiments/ 创建 {name}.json
定义 sheets[] → cells[][] 网格矩阵
设置 label / input(validation+readingGuard) / computed(expression+variables)
步骤 2(青色):Pydantic 验证
图标:Pydantic 徽标 + 对勾
内容:python -c "from app.core.config_loader import config_service;
c = config_service.load_validated('{name}')"
自动递归验证所有嵌套字段
成功 → assert len(c.sheets) > 0
步骤 3(紫色):注册实验
图标:注册表 + 加号
内容:在 frontend/src/assets/experiences.json 添加条目
{ "id": "xxx", "title": "实验名", "stage": [{ "type":"experiment", ... }] }
指定 config provider URL + validation URL
步骤 4(红色):前端加载
图标:浏览器 + 加载动画
内容:ExperienceSwitch 读取 experiences.json → 显示新实验卡片
点击卡片 → ExperienceFrame → ExperimentPage
→ store.loadConfigFromUrl() → setConfig() → 自动初始化
步骤 5(金色):运行验证
图标:对勾 + 终端窗口
内容:cd frontend && yarn type-check && yarn build
cd backend && python -c "验证命令"
无需修改任何 .ts / .py 代码!
【底部(占高 25%)— 三个关键设计原则卡片】
卡片一:store.setConfig() 自动处理
遍历所有 cells → 识别 input type → 初始化 data[fieldId]
识别 computed type → 初始化 areaResults[areaId]
无需手动声明任何 field
卡片二:级联计算自动发现
findComputedCell() + variables[] → 自动建立依赖图
updateAreaCalculations() 递归解析任意嵌套依赖
无需手动指定计算顺序
卡片三:前后端类型通用
GridLabelCell / GridInputCell / GridComputedCell 是通用模型
任何实验只改变 JSON 内容,不改变 Schema
新实验完全零代码侵入
【顶部标注】一个从「声速测量」箭头发散到「杨氏模量」「惠斯通电桥」「迈克尔逊干涉仪」的扇形扩展图
```
---
## 补充说明
所有生图 prompt 中涉及的技术流程均基于代码真实逻辑提取,关键对照:
| 流程 | 对应源文件 |
|------|-----------|
| 字段验证 | `backend/app/core/validation.py` + `backend/app/api/value.py` |
| 读数守卫 | `backend/app/core/reading_guard.py` (290 lines) |
| 峰值检测 | `backend/app/core/peak_detector.py` (127 lines) |
| 级联计算 | `frontend/src/stores/experiment.ts` updateAreaCalculations() |
| LaTeX 转换 | `frontend/src/utils/calculation.ts` convertLatexToMathJS() |
| AI 通信 | `frontend/src/utils/aiClient.ts` (297 lines) |
| 配置加载 | `backend/app/core/config_loader.py` |
| 示波器驱动 | `backend/app/hardware/oscilloscope.py` + `service.py` |
| 会话管理 | `backend/app/core/session_store.py` |
| PDF 导出 | `frontend/src/utils/pdfExport.ts` |
| 类型对齐 | `backend/app/schemas/experiment.py` ↔ `frontend/src/types/experiment.ts` |
| 路由守卫 | `frontend/src/router/index.ts` beforeEach |

查看文件

@ -0,0 +1,717 @@
# AI + 声速测量实验 —— 大学生物理实验竞赛项目调研说明
> **赛道**:AI + 物理实验赛道 | **实验主题**:超声波声速测量
> **团队**:AI + 声速测量实验 团队 | **竞赛**:全国大学生物理实验竞赛
---
## 一、项目概述
本项目构建了一套 **AI 深度融合的物理实验教学一体化平台 (PhyExp)**,以大学物理经典实验 "超声波声速测量" 为切入点,实现了 **预习—测验—实验—考试—总结** 全流程的数字化、智能化教学闭环。
平台采用 **前后端分离架构**(Vue 3 + FastAPI),通过 **配置驱动** 的实验定义引擎,将硬件数据采集、AI 多角色教学辅助、实时级联计算、智能验证守卫等技术深度融合,打造了一个可复用于任意物理实验的通用教学框架。
---
## 二、创新点
### 创新点一:AI 多角色深度嵌入教学全流程
区别于常见的 "外挂式 AI 对话框",本项目的 AI 助手以 **三个独立教学角色** 深度嵌入实验的每一个阶段:
| 角色 | teacherType | 触发时机 | 功能 |
|------|-------------|----------|------|
| **智能助教** | `question` | 预习阶段 SSE 流式对话 | 基于预习资料上下文解答学生疑问,支持结构化分层回答(核心概念/直接回答/理解提示/深入说明/实验提示/自检问题) |
| **数据评价官** | `data_eval` | 实验阶段鼠标悬停 600ms | 基于全量实验数据快照 + 学生信息,对单个单元格数据给出等级评定、相对误差分析、数据质量评估、教师评语、改进建议 |
| **智能批卷官** | `grader` | 测验提交后 | 对错题进行诊断分析,输出正确性反馈、错误诊断、知识点评估、改进建议、拓展问题 |
**AI 与实验数据的深度融合**:
- 在实验数据表中悬停任意单元格,AI 不仅获取该单元格的值,还获取 **全部已填入的实验数据 + 全部计算结果 + 实验配置元信息 + 学生信息**,提供全局视角的评价
- 支持 **单元格检查模式 (Cell Inspector)**:点击任意实验表格单元格,其完整上下文(所属表、字段类型、值、单位、验证规则)自动注入 AI 对话上下文
- AI 请求/响应完整日志记录,支持调试回溯
### 创新点二:硬件-软件-算法全链路集成
实现了从物理实验仪器到教学软件的 **无断点数据链路**:
```
示波器 (USB/SCPI) → 峰值检测状态机 → OCR 读数模拟 → 读数守卫验证 → 实验数据表 → AI 评价
```
**核心机制**:
1. **示波器直连采集**:通过 PyUSB + SCPI 协议直接驱动 OWON NDS102U 示波器,实时获取通道频率和峰值电压,支持自动回退到模拟模式以适配无硬件开发环境
2. **峰值检测状态机**:独立后台线程 0.3s 间隔轮询示波器 CH2 峰值,实现 `IDLE → RISING → PEAK_TRIGGERED → COOLDOWN` 四态自动检测,模拟真实的 "缓慢转动旋钮寻找波形峰值" 实验操作流程
3. **读数守卫 (ReadingGuard)**:强制学生按顺序读数并比对硬件参考值,采用 **二级容差机制**(容忍差 = 警告但通过,严格差 = 拒绝),确保学生确实使用仪器进行了测量而非编造数据
4. **游标卡尺 OCR 模拟**:预设 10 组标准距离值并叠加随机噪声,模拟游标卡尺读数 OCR 识别过程,为未来接入真实 OCR 模块预留接口
### 创新点三:配置驱动的通用实验框架
实验内容 **完全由 JSON 配置文件定义**,无需修改任何代码即可新增实验:
```json
// 声速测量实验仅是一个 JSON 配置文件的实例化
// 同一个框架可复用于:杨氏模量测量、惠斯通电桥、迈克尔逊干涉仪 等任意物理实验
```
- **多维表格布局**:支持多个 Sheet(类似 Excel 工作表),每个 Sheet 为二维网格,行列自由定义
- **单元格类型**:`label`(LaTeX 标签)、`input`(学生输入+验证规则)、`computed`(自动计算)、`null`(占位)
- **跨列/跨行**:支持 `colSpan` / `rowSpan` 实现复杂表头
- **控制栏**:每个 Sheet 可配置硬件控制按钮(如 "启动峰值监控"/"停止峰值监控")
- **验证规则**:每个输入单元格独立配置数值范围/正则/必填/读数守卫
- **前后端类型对齐**:Pydantic v2 与 TypeScript 接口双向同步定义
### 创新点四:实时级联计算引擎
实现了一套 **LaTeX 数学表达式 → mathjs 编译求值** 的自动化计算管道:
| 处理阶段 | 示例 |
|----------|------|
| LaTeX 输入 | `\frac{2}{5} \sum_{i=1}^{5} (L_{i+5} - L_i)` |
| 转换后 | `(2)/(5) * ((L6-L1)+(L7-L2)+(L8-L3)+(L9-L4)+(L10-L5))` |
| mathjs 编译 | 编译为执行树 |
| 变量代入 | `{ L1: 144.02, L2: 148.80, ... }` |
| 格式输出 | `formatNumber(result, "0.000")` → `"15.636"` |
**依赖图递归解析**:系统自动构建所有计算单元的依赖关系图,输入变化时仅重算受影响的 cascade 链,支持循环引用检测。
### 创新点五:视觉化即时反馈的 Excel 风格数据界面
- **五态颜色编码**:白色(未填)→ 蓝色(获焦)→ 黄色(已填待验)→ 绿色(通过)→ 红色(失败),学生一目了然
- **LaTeX 原生渲染**:表头、标签、单位均使用 KaTeX 实时渲染数学公式
- **PDF 一键导出**:通过 html2canvas + jsPDF 将实验数据表导出为 A4 PDF 报告
- **设备自适应**:支持 mobile / tablet / desktop 三级响应式布局
### 创新点六:三种测量方法对比实验设计
本实验同时在同一个平台上对比三种声速测量方法:
| 方法 | 原理 | 计算方式 |
|------|------|----------|
| 驻波法 | 半波长驻波共振 | λ = 2·mean(ΔL)/1000, v = f·λ |
| 相位法 | 利萨如图形相位比较 | 同驻波法 |
| 时差法 | 脉冲时间差 | v = mean(ΔL/1000) / mean(ΔT/1e6) |
三种方法的测量结果均与 **温度校正理论值** (v₀ = 331.5 + 0.6·t) 比较,计算相对误差,最终汇总到对比表中。
---
## 三、系统架构
### 整体架构图
```
┌─────────────────────────────────────────────────────────────┐
│ 浏览器 (Vue 3 SPA) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────────────┐ │
│ │ Vue 3 │ │ KaTeX │ │ Pinia Store │ │
│ │ Router │ │ mathjs │ │ (experiment/student) │ │
│ │ (hash) │ │ (计算) │ │ │ │
│ └──────────┘ └──────────┘ └──────────────────────────┘ │
│ │ │ │
│ │ HTTP REST ─────────────────┤ SSE Streaming │
└─────────┼────────────────────────────┼──────────────────────┘
│ │
┌─────────┼────────────────────────────┼──────────────────────┐
│ ▼ FastAPI 后端 ▼ AI 服务(外部) │
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ api/ │ │ core/ │ │ schemas/ │ /api/chat│
│ │ 路由层 │→ │ 业务层 │← │ Pydantic v2 模型 │ ·question│
│ │ form.py │ │ ·配置加载 │ │ ·实验配置模型 │ ·data_eval│
│ │ value.py │ │ ·字段验证 │ │ ·验证请求/响应 │ ·grader │
│ │ device.py│ │ ·读数守卫 │ │ ·测量分析模型 │ │
│ │ measure. │ │ ·测量分析 │ └──────────────────┘ │
│ │ peak_mon │ │ ·OCR服务 │ │
│ │ debug.py │ │ ·峰值检测 │ │
│ └──────────┘ │ ·会话存储 │ │
│ └──────────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │ hardware/ │ │
│ │ ·示波器驱动 │ PyUSB SCPI │
│ │ ·服务封装 │ (自动回退模拟) │
│ └────────────┘ │
│ │
│ config/experiments/ │
│ └── cn.edu.muc.lxy.phyexp.voicespeed.json (7 Sheets) │
└──────────────────────────────────────────────────────────────┘
```
### 前端组件层级
```
App.vue
└── RouterView (hash路由)
└── ExperienceFrame.vue (实验主框架)
├── LearnPage.vue (预习:视频 + AI 助教 SSE 流式对话)
├── QuizPage.vue (测验:试题渲染 + AI 智能批改)
└── ExperimentPage.vue (实验数据记录)
├── ExperimentForm.vue (状态管理 + provide AIEvalContext)
│ └── ExperimentGrid.vue × N (每个 Sheet 一个 Excel 网格)
│ └── ExperimentGridCell.vue × M (label|input|computed)
│ ├── 颜色编码验证状态 (白/蓝/黄/绿/红)
│ ├── LaTeX 实时渲染
│ └── AI 悬停评价 Tooltip (teacherType=data_eval)
├── ExperimentPrintTable.vue (隐藏,供 PDF 导出)
└── AIChatSidebar.vue (浮动可拖拽 AI 对话面板)
├── 单元格检查模式 (Cell Inspector)
└── 结构化回答展示
```
### 数据流
```
1. 配置加载: GET /form → ExperimentGridConfig (7 Sheets, ~80 cells)
2. 数据输入: 用户输入 → store.setFieldValue() → 标记未验证 → 触发级联重算
3. 后端验证: 失焦 → POST /value → FieldValidator → ReadingGuardManager → SessionStore
4. 验证反馈: { accept, message, severity } → 单元格背景色更新
5. 级联计算: store.updateAreaCalculations() → 递归依赖图 → mathjs 求值
6. AI 评价: 悬停 600ms → POST /api/chat (teacherType=data_eval) → 结构化评价 Tooltip
7. PDF 导出: html2canvas 截取 → jsPDF 合成 → 下载
```
### 声速实验配置结构 (7 个 Sheet)
| Sheet ID | 名称 | 列数 | 内容 |
|----------|------|------|------|
| `basic_info` | 基本信息 | 3 | 班级、姓名、学号 |
| `table1_frequency` | 表1 声源频率与介质温度 | 6 | f1~f5 (设备读数)、温度、频率均值、理论声速 v₀ |
| `table2_standing` | 表2 驻波法 | 6 | 10 位距离读数 + 5 个半波长差 + λ + v + 误差 |
| `table3_phase` | 表3 相位法 | 5 | 同驻波法结构,使用利萨如图形判定 |
| `table4_timediff` | 表4 时差法 | 10 | 10 位距离 + 10 个时间 + 差值 + v + 误差 |
| `table5_compare` | 表5 方法比较 | 3 | 三种方法 v 和误差横向对比 |
| `notes` | 实验现象与结论 | 1 | 自由文本:现象记录 + 误差分析 |
### 技术栈
| 端 | 核心技术 | 版本 |
|----|----------|------|
| 前端 | Vue 3, TypeScript, Vite, Pinia, KaTeX, mathjs | 3.5 / 5.9 / 7 / 3 / 0.16 / 15 |
| 后端 | FastAPI, Pydantic v2, Uvicorn | 0.116+ / 2.11+ / 0.35+ |
| 硬件 | PyUSB, libusb | 1.3+ |
| AI | REST + SSE (Server-Sent Events) | 外部服务 |
| 导出 | html2canvas + jsPDF | 1.4 / 3 |
| 包管理 | yarn (前端) + uv (后端) | — |
---
## 四、声速实验计算公式
### 驻波法 / 相位法
$$\Delta L_i = L_{i+5} - L_i \quad (i = 0,1,2,3,4)$$
$$\lambda = \frac{2}{5} \cdot \overline{\Delta L} \times 10^{-3} \ (\text{m})$$
$$v = f \cdot \lambda \quad \Delta v = f \cdot \frac{2 \cdot \sigma(\Delta L)}{1000}$$
### 时差法
$$v_i = \frac{\Delta L_i / 1000}{\Delta T_i / 10^6} \quad v = \overline{v_i} \quad \Delta v = \sigma(v_i)$$
### 理论声速 (温度校正)
$$v_0 = 331.5 + 0.6 \cdot t \ (\text{m/s})$$
### 相对误差
$$A_\% = \frac{|v - v_0|}{v_0} \times 100\%$$
---
## 五、AI 生图用 Prompt
> **全局风格锁**(每页必须继承):交付物为 **单张 1920×1080 横版 PPT 完整页面**,非插图素材。画面中所有中文文字由生图 AI 直接渲染在图像中,不得留白让后期添加。
>
> **统一视觉规范**:
> - **主色调**:深海蓝 `#0B1E3D` → 科技蓝 `#1A56DB` 渐变;强调色:琥珀金 `#F59E0B`;辅助色:青绿 `#10B981`、紫罗兰 `#7C3AED`
> - **字体**:标题使用粗体无衬线黑体风格(28-36pt),正文使用常规无衬线字体(14-18pt),公式使用衬线数学风格
> - **背景**:封面/总结页使用深色渐变背景;内容页使用极浅灰 `#F0F4F8` 背景,上方保留约 80px 深蓝横条标题栏
> - **插图风格**:统一采用扁平矢量插画 + 等距 3D 图标风格,线条干净利落,无复杂纹理;光影用柔和渐变模拟
> - **装饰元素**:每页左上角 20pt 蓝色小圆点 + 页号;标题栏右侧统一放置实验装置剪影图标(超声波探头/示波器/声波弧线);页脚统一放置 2px 深蓝细线
> - **卡片规范**:圆角 12px,浅色填充 `#FFFFFF`,外阴影 `0 4px 16px rgba(11,30,61,0.08)`;卡片内图片与文字上下布局,图占卡片 40% 高度
> - **统一插图元素集**(在各页中按需选用):超声波探头(发射+接收)、示波器屏幕(含波形)、声波弧线涟漪、游标卡尺、AI 芯片/大脑、齿轮、盾牌、L形实验导轨、温度计、试管/烧杯、笔记本屏幕、JSON 花括号、学生/教师人物剪影、箭头管线
---
### 第 1 页:封面
```
生成一张 1920×1080 横版 PPT 封面。严格遵循全局风格锁。
【背景】深色渐变背景,从页面左上角 #0B1E3D 过渡到右下角 #1A3A6B。背景中分布半透明的声波同心圆弧(从右下角超声波探头发出,淡蓝色,透明度 15%),以及细密的网格点和电路走线纹理(透明度 8%)。
【插图】
- 右下角:一只 3D 等距风格的超声波探头(银灰色金属质感,发射面朝向左上方),探头前方发出三道同心圆弧形声波,渐变为淡蓝半透明
- 左上角:AI 芯片图标(紫罗兰色发光节点,5×5 网格连线矩阵),悬浮半透明
- 中下部偏右:一只简化的示波器屏幕轮廓,内部显示一条正弦波曲线(青绿色描边,发光效果)
【文字】
- 主标题(页面正中偏上,42pt,白色加粗发光):AI + 声速测量实验
- 副标题(主标题下方 40px,20pt,淡蓝色 #93C5FD):面向大学物理实验教学的智能化一体化平台
- 底部两行(距底边 80px,14pt,白色 70% 透明度):
行一:全国大学生物理实验竞赛 · AI+物理实验赛道
行二:AI + 声速测量实验 团队
- 主标题与副标题之间:一条 200px 琥珀金色渐变细线(#F59E0B → 透明)
【页脚装饰】底部 2px 深蓝 #0B1E3D 贯穿线。右上角 "01" 页号 + 蓝色圆点。
```
---
### 第 2 页:选题背景与痛点
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰 #F0F4F8 底,顶部 80px 深蓝 #0B1E3D 横条标题栏,标题栏右侧放置超声波探头剪影。
【标题栏文字】白色 28pt 粗体:选题背景与核心痛点
【左侧区域 - 四大痛点(占宽 55%)】四张纵向排列的白色圆角卡片,每张含插图+文字:
卡片一(红色系):
- 插图(左小图):一只笔在实验报告上随意填写数字的矢量插画,数字旁放一个红色问号
- 标题(红色 #DC2626 粗体 16pt):数据造假难识别
- 正文(深灰 13pt):学生可随意填写编造数据,教师无法验证数据是否真实来源于仪器测量
卡片二(橙色系):
- 插图(左小图):一个大教室中一位教师面对众多举手学生的场景剪影
- 标题(橙色 #EA580C 粗体 16pt):指导资源严重不足
- 正文(深灰 13pt):1对N大班教学,教师无法及时为每位学生解答实验中的个性化疑问
卡片三(黄色系):
- 插图(左小图):桌面上散落计算器、草稿纸(写满 λ、v 等公式),学生烦恼表情
- 标题(琥珀色 #D97706 粗体 16pt):计算繁琐易出错
- 正文(深灰 13pt):λ、v、误差分析等多项指标需手动计算,过程冗长且极易出错
卡片四(蓝色系):
- 插图(左小图):日历翻页动画(从实验日跳到数天后),一份标着 "?" 的实验报告
- 标题(蓝色 #2563EB 粗体 16pt):评价反馈严重滞后
- 正文(深灰 13pt):实验报告提交后需等待数天才能获得评分,错过最佳纠错时机
【右侧区域 - 解决方案(占宽 40%)】
- 顶部一个大型发光箭头(金色渐变)指向右侧智能芯片图标
- 芯片图标中央标注 "AI+",周围环绕 5 个发光节点,节点文字:硬件直连 | 实时验证 | AI 指导 | 自动计算 | 即时评价
- 芯片下方标注文字(15pt 深蓝 #1E3A8A 粗体):本项目的解决方案
【装饰】页号 "02" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 3 页:核心创新一 — AI 多角色深度融合
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:核心创新一:AI 多角色深度融合教学全流程
【顶部插图区 — 实验流程带(占高 20%)】五个圆角矩形节点横向排列,弧形箭头连接:
预习 → 测验 → 实验 → 考试 → 总结
每个节点上方标注对应 AI 角色名称。预习节点上方标注"智能助教"(青绿色),测验节点上方标注"智能批卷官"(橙色),实验节点上方标注"数据评价官"(紫色)。
【主体区域 — 三张 AI 角色卡片(占高 65%)】横向等距排列:
卡片一(青绿色调 #10B981):
- 顶部插图(占卡片 40%):一位学生面对电脑屏幕,屏幕中 AI 对话界面分层展示"核心概念→直接回答→理解提示→深入说明",对话气泡用青绿渐变
- 角色名称(16pt 粗体):智能助教 · question
- 场景标注(12pt 灰):预习阶段 · SSE 流式对话
- 功能描述(12pt 深灰):基于课程资料上下文实时解答疑问,结构化分层回答涵盖概念阐述、直接解答、理解提示与延伸思考
卡片二(紫色调 #7C3AED):
- 顶部插图(占卡片 40%):实验数据表格上方悬停鼠标光标,光标旁弹出评分气泡(四星评级、误差百分比、评语),气泡用紫色半透明毛玻璃效果
- 角色名称(16pt 粗体):数据评价官 · data_eval
- 场景标注(12pt 灰):实验阶段 · 单元格悬停600ms触发
- 功能描述(12pt 深灰):获取全量实验数据快照+学生信息,逐字段给出等级评定、相对误差分析、数据质量评估与个性化改进建议
卡片三(橙色调 #EA580C):
- 顶部插图(占卡片 40%):一份批改后的试卷,错题被红色圈出,旁边 AI 展开诊断卡片(知识点评估、错误分析、拓展问题),批改笔迹为橙色
- 角色名称(16pt 粗体):智能批卷官 · grader
- 场景标注(12pt 灰):测验提交后自动触发
- 功能描述(12pt 深灰):错题诊断分析,输出正确性反馈、知识点评估、改进建议与针对性拓展问题
【底部信息条】一段连接各角色的弧形虚线标注:"三角色贯穿实验全流程,AI 不是外挂工具而是教学闭环的核心组件"
【装饰】页号 "03" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 4 页:核心创新二 — 硬件到AI全链路数据闭环
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:核心创新二:硬件-软件-算法全链路数据闭环
【主体 — 从左到右六节点管道图(占高 60%)】
节点之间用渐变色(蓝→紫→金)粗箭头连接,箭头内标注数据格式。
节点一(左上区,蓝色调):示波器直连采集
- 插图:OWON NDS102U 示波器正面板矢量图,屏幕上显示正弦波和频率读数
- 标注文字:USB/SCPI 协议 · 实时频率+峰值采集
节点二(中上区,青色):峰值检测状态机
- 插图:四个状态圆圈循环连接(IDLE→RISING→PEAK_TRIGGERED→COOLDOWN),当前状态高亮,用波形曲线示意上升/下降趋势
- 标注文字:IDLE → RISING → PEAK → COOLDOWN · 0.3s 间隔轮询
节点三(中区,紫色):OCR 读数模拟
- 插图:游标卡尺刻度盘特写,刻度线上叠加 OCR 识别框和识别结果数字,旁有"±0.02mm 噪声"标注
- 标注文字:游标卡尺 OCR 识别 · 10 组预设标准值 + 随机噪声
节点四(中下区,红色):读数守卫校验
- 插图:盾牌图标 + 二级容差进度条(绿色区→黄色警告区→红色拒绝区),旁有"严格差=拒绝"和"容忍差=警告通过"标注
- 标注文字:顺序守卫 · 双级容差 · 硬件参考值比对
节点五(右下区,绿色):级联计算引擎
- 插图:齿轮组咬合运转 + LaTeX 公式 → mathjs 代码块的转换示意图(\frac{a}{b} 变成 (a)/(b))
- 标注文字:LaTeX→mathjs 编译求值 · 级联依赖图自动重算
节点六(右端,金色):AI 数据评价
- 插图:AI 芯片向外发射分析射线,射线触及数据表格后返回评分气泡
- 标注文字:全量数据快照 → teacherType=data_eval → 结构化评价
【底部(占高 15%)】带盾牌+齿轮+芯片图标的横幅:
支持 SIMULATED 模式自动回退 —— 无真实硬件环境下系统自动切换模拟数据,开发与演示零障碍
【装饰】页号 "04" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 5 页:系统技术架构总览
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:系统技术架构总览
【主体 — 三层水平分区(占高 70%)】
第一层(蓝色调 #1E40AF 背景,高约 25%)— 前端展示层
- 左侧大型标注(白色 18pt 粗体):Vue 3 SPA 前端
- 六个带图标的圆角方块横向排列:
方块 1(路由图标):Vue Router
方块 2(数据库图标):Pinia Store
方块 3(公式图标):KaTeX 渲染
方块 4(计算器图标):mathjs 计算
方块 5(PDF 图标):html2canvas+jsPDF
方块 6(对话气泡图标):AI Chat 组件
- 方块下方标注(白色半透明 11pt):TypeScript 5.9 · Vite 7 · hash 路由
第二层(青绿色调 #059669 背景,高约 25%)— 后端业务层
- 左侧大型标注(白色 18pt 粗体):FastAPI 后端
- 六个带图标的圆角方块横向排列:
方块 1(文档图标):表单配置加载
方块 2(对勾图标):字段验证
方块 3(盾牌图标):读数守卫
方块 4(波形图标):峰值检测
方块 5(计算图标):测量分析
方块 6(数据库图标):会话存储
- 方块下方标注(白色半透明 11pt):Python · Pydantic v2 · Uvicorn
第三层(紫色调 #6D28D9 背景,高约 25%)— 数据与硬件层
- 左侧大型标注(白色 18pt 粗体):数据源
- 四个带图标的圆角方块横向排列:
方块 1(JSON 花括号图标):实验 JSON 配置
方块 2(USB 接口图标):PyUSB 示波器驱动
方块 3(AI 芯片图标):AI 服务 (REST+SSE)
方块 4(文件夹图标):内存会话存储
- 方块下方标注(白色半透明 11pt):config/experiments/*.json · 自动回退模拟模式
【层间连接】
- 第一层与第二层之间:双向箭头,标注 "REST API · JSON 序列化"
- 第二层与第三层之间:双向箭头,标注 "SCPI 指令 · 会话管理"
- 右侧纵向贯穿整三层的标注条(竖排,金色):Pydantic v2 ↔ TypeScript 前后端类型对齐
【底部(占高 15%)】左侧放置三只实验仪器剪影图标(示波器 + 超声波探头导轨 + 游标卡尺),右侧文字:声速测量实验已完整实现 · 框架可复用至任意物理实验
【装饰】页号 "05" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 6 页:配置驱动的通用实验框架
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:核心创新三:配置驱动的通用实验框架
【左侧区域(占宽 42%)— JSON 配置可视化】
上半部 — JSON 配置结构树:
一张深色背景(#1E293B)代码风格面板,左侧边缘有彩色竖线标识层级。
第一层(蓝色竖线):{ "title": "声速测量实验", "sheets": [ ... ] }
第二层(绿色竖线,缩进):{ "id": "table2_standing", "columns": 6 }
第三层(紫色竖线,再缩进):"cells": [[ ... ]]
第四层(金色竖线):{ "type": "input", "fieldId": "s_l0", ... }
第五层(粉红竖线):"validation": { "type": "number", "min": 100, "max": 200 }
每层旁边用彩色小标签标注:根节点 / Sheet定义 / 单元格矩阵 / 输入字段 / 验证规则
下半部 — 单元格类型图例:
三张小卡片:
[label] 标签单元格 — 静态 LaTeX 文本标签,支持 colSpan/rowSpan
[input] 输入单元格 — 学生数据输入,带验证规则+读数守卫+单位
[computed] 计算单元格 — 自动求值,带 LaTeX 表达式+变量依赖+格式
【右侧区域(占宽 53%)— 可扩展性展示】
三张实验卡片竖直等距排列:
卡片一(实线边框,蓝色调)— 已完成实验:
- 顶部插图:声速测量实验的 7 个 Sheet 标签页水平排列示意(基本信息/表1~表5/备注),选中的标签高亮
- 正文:超声波声速测量 · 7 Sheets · ~80 个单元格 · 三种测量方法对比
- 底部标签(绿色):✅ 已部署
卡片二(虚线边框,紫色调)— 可扩展:
- 顶部插图:拉伸试验机 + 光杠杆示意图
- 正文:杨氏模量测量实验 · 配置即添加
- 底部标签(蓝色):🔧 仅需编写 JSON
卡片三(虚线边框,橙色调)— 可扩展:
- 顶部插图:惠斯通电桥电路示意图
- 正文:惠斯通电桥实验 · 配置即添加
- 底部标签(蓝色):🔧 仅需编写 JSON
【底部带状区(贯穿全宽,深蓝背景)】白色文字横向排列 7 个特性标签,用 "×" 分隔:
多维表格 × LaTeX 数学渲染 × 级联自动计算 × 读数守卫 × 硬件控制栏 × 跨列跨行布局 × 设备响应式适配
【装饰】页号 "06" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 7 页:实验数据记录界面展示
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:实验界面展示 — Excel 风格网格表格 + AI 实时评价
【主体 — 核心界面模拟(占高 75%)】
中央偏左(占宽 60%):实验数据表格模拟截图
- 模拟一个浏览器窗口边框(圆角,浅灰边框,顶部有三色窗口按钮红黄绿)
- 窗口内展示一个完整的表格界面:
- 顶部 Sheet 标签栏:基本信息 | 表1频率 | 表2驻波法(当前选中) | 表3相位法 | 表4时差法 | 表5对比 | 备注
- 表格区域:约 6 列 × 5 行可视区域,有表头(测量项目 / 1 / 2 / 3 / 4 / 5),斑马纹交替行色
- 第 1 行:左侧 LaTeX 标签 "f/kHz",右侧 5 个输入框分别显示数值且背景色各异——绿色(36.540 通过)/绿色(36.545 通过)/黄色(36.538 待验)/白色(空)/红色(40.2 超范围)
- 第 2 行:左侧 LaTeX 标签 "v₀/(m·s⁻¹)",右侧一个跨 5 列的自动计算区显示蓝色计算结果 "345.82"
- 第 3 行(驻波法区):左侧标签 "L₀/mm",右侧显示绿色输入框 "144.02"
- 第 4 行(驻波法区):左侧标签 "λ/mm",右侧显示蓝色自动计算结果 "15.636"
- 表格上方显示控制栏按钮:"启动峰值监控"(绿色圆角按钮)
中央偏右(占宽 35%):AI 评价浮层
- 一个从表格右侧某绿色单元格引出的虚线连接线,指向一个浮层卡片
- 浮层卡片(白色毛玻璃效果,圆角,投影):
- 顶部标题(紫色小字):AI 数据评价 · 悬停 600ms 触发
- 评价对象标注:字段 s_l0(L₀ 驻波法第1个读数)
- ⭐ 等级评定:A — 数据优秀
- 📊 相对误差:0.32%(与参考值偏差极小)
- 📝 数据质量:频率读数稳定,五位有效数字规范
- 💬 教师点评:频率测量精度符合要求,注意温度计读数应保留一位小数
- 🔧 改进建议:建议重复测量3次取均值以降低随机误差
右下角:AI 对话面板(缩小版)
- 一个可拖拽对话面板的小型示意,显示预习 Q&A 对话片段:
学生气泡:"请解释驻波法的物理原理"
AI 气泡(结构化回答):"核心概念:驻波是两列同频率反向传播波的叠加...理解提示:想象一根两端固定的弦..."
【底部 — 状态颜色图例条】
横向排列四个带颜色圆点 + 说明的小方块:
⬜ #FFFFFF 未填写 | 🟦 #E8F0FE 获焦中 | 🟨 #FFF3CD 待验证 | 🟩 #D4EDDA 验证通过 | 🟥 #F8D7DA 验证失败
【装饰】页号 "07" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 8 页:级联计算引擎详解
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:核心创新四:实时级联计算引擎
【左侧区域(占宽 52%)— LaTeX → mathjs 转换流水线】
四个步骤纵向排列,每个步骤一个水平卡片,步骤间用粗体向下箭头连接:
步骤一卡片(蓝色调):
- 左侧编号圆:①
- 顶部插图:一页 LaTeX 公式代码(深色代码背景,彩色语法高亮),内容为:\frac{2}{5}\sum_{i=1}^{5} (L_{i+5} - L_i)
- 正文(14pt):原始 LaTeX 表达式 —— 从 JSON 配置文件的 expression 字段直接提取,支持 \frac、\sqrt、\sum、希腊字母、上下标等完整 LaTeX 数学语法
步骤二卡片(紫色调):
- 左侧编号圆:②
- 顶部插图:一个箭头指向的转换对照表(左栏 LaTeX / 右栏 mathjs),逐行展示 \frac{a}{b}→(a)/(b)、\sqrt{a}→sqrt(a)、\times→*、\lambda→lambda、v_{1}→v1
- 正文(14pt):语法转换 —— convertLatexToMathJS() 递归遍历 AST,分步骤完成分数转换、根号转换、希腊字母替换、下标扁平化、数学符号映射
步骤三卡片(绿色调):
- 左侧编号圆:③
- 顶部插图:抽象语法树示意图,树根为 OperatorNode(+),分支为乘法/除法/加法节点,叶子为 SymbolNode(L6、L1...)和 ConstantNode(2、5)
- 正文(14pt):mathjs 编译 —— math.compile() 将转换后的字符串编译为可执行表达式树,缓存编译结果以提升后续求值效率
步骤四卡片(金色调):
- 左侧编号圆:④
- 顶部插图:一棵变量赋值表,左侧列变量名(L1=144.02, L2=148.80...),右侧显示最终结果 "15.636"(蓝色高亮),下方标注 formatNumber(15.636, "0.000")
- 正文(14pt):变量求值 + 格式化输出 —— compiled.evaluate(variables) 代入实验实测数据求值,formatNumber() 按配置的格式字符串输出
【右侧区域(占宽 43%)— 依赖图级联解析】
顶部 — 依赖关系网络图:
一张节点+有向边构成的依赖关系 DAG 图(深色背景),节点使用彩色圆角矩形:
- 蓝色节点:f1, f2, f3, f4, f5(输入字段)
- 绿色节点:frequency_avg(计算字段)
- 蓝色节点:L0~L9(输入字段)
- 紫色节点:ΔL1~ΔL5(中间计算)
- 橙色节点:ΔL_avg(中间计算)
- 金色节点:λ(关键中间量)
- 红色节点:v(最终结果)
- 粉色节点:误差
- 蓝色节点:温度(输入字段)
- 绿色节点:v₀(理论值)
- 粉色节点:误差
有向边从依赖指向被依赖。图中用虚线方框圈出"输入变化传播区域",标注"输入 L3 变化 → 仅重算 ΔL1~ΔL3 + ΔL_avg + λ + v + 误差,共 7 个节点"
底部 — 关键特性标注(三个小图标+文字):
🔄 递归依赖图解析(支持深层嵌套依赖) | 🚫 循环引用自动检测(visitedAreas Set 防止死循环) | ⚡ 增量级联重算(仅更新受影响的 cascade 链)
【装饰】页号 "08" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 9 页:三种声速测量方法对比
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】浅灰底,顶部深蓝横条标题栏。标题栏文字:实验设计 — 三种声速测量方法同平台对比
【主体 — 三栏对比布局(占高 70%)】
左栏 — 驻波法(蓝色调 #3B82F6 卡片,占宽 30%):
- 顶部大插图(占卡片 35%):两个超声波探头面对面放置在一根带刻度的导轨上,两探头之间用蓝色半透明波形绘制出 5 个半波长的驻波图案(波节用白点标注,波腹用红色亮点标注),下方标注 L₀ ~ L₉ 共 10 个读数位置
- 标题(白色 16pt 粗体,蓝色背景头):方法一 · 驻波法
- 原理(13pt):半波长驻波共振,缓慢移动接收器寻找振幅极大值点,记录相邻极大值位置 Lᵢ
- 公式区(深蓝背景代码风格,白色公式):
ΔLᵢ = L_{i+5} - L_i
λ = (2/5)·mean(ΔL)/1000 [m]
v_standing = f · λ
中栏 — 相位法(紫色调 #7C3AED 卡片,占宽 30%):
- 顶部大插图(占卡片 35%):实验室示波器屏幕特写,屏幕上显示一个倾斜的利萨如椭圆,在椭圆旁标注"相位差 = π/4";屏幕下方标注"椭圆→直线→椭圆→直线",每经过一条直线对应相位变化 2π,即移动一个波长
- 标题(白色 16pt 粗体,紫色背景头):方法二 · 相位法
- 原理(13pt):利萨如图形相位比较法,示波器 X-Y 模式下椭圆变为直线时相位差为 2π 整数倍
- 公式区(深紫背景代码风格,白色公式):
ΔLᵢ = L_{i+5} - L_i
λ = (2/5)·mean(ΔL)/1000 [m]
v_phase = f · λ
右栏 — 时差法(绿色调 #10B981 卡片,占宽 30%):
- 顶部大插图(占卡片 35%):脉冲波形传播示意图——发射探头发出一个尖锐脉冲(红色三角波),沿导轨传播到接收探头,示波器屏幕上显示发送脉冲(T₁)和接收脉冲(T₂)之间的时间间隔 ΔT,用双箭头标注。下方标注 L₁~L₁₀ 距离读数和 T₁~T₁₀ 时间读数
- 标题(白色 16pt 粗体,绿色背景头):方法三 · 时差法
- 原理(13pt):脉冲时间差法,测量超声波脉冲在不同距离间的传播时间,由距离差和时间差直接计算声速
- 公式区(深绿背景代码风格,白色公式):
vᵢ = (ΔLᵢ/1000) / (ΔTᵢ/10⁶)
v_time = mean(vᵢ)
【底部横向贯穿带(深蓝背景,占高 15%)】
- 左侧温度计图标 + 公式(白色 14pt):理论声速 v₀ = 331.5 + 0.6·t [m/s](温度校正公式)
- 中央箭头(金色):将三种方法的 v 值与 v₀ 比对 → 计算相对误差 A% = |v-v₀|/v₀ × 100%
- 右侧对比表格缩影(三行):驻波法 v=xxx m/s, A%=x.x% | 相位法 v=xxx m/s, A%=x.x% | 时差法 v=xxx m/s, A%=x.x%
【装饰】页号 "09" 左上角蓝色圆点,底部 2px 深蓝细线。
```
---
### 第 10 页:总结与展望
```
生成一张 1920×1080 横版 PPT 内容页面。严格遵循全局风格锁。
【背景】深色渐变背景(同封面风格),从左上角 #0B1E3D 过渡到右下角 #312E81(深靛蓝)。背景中分布淡化的超声波弧线、AI 节点连线、数据表格网格等混合图案(透明度 10%)。
【标题区(占高 12%)】居中大字(36pt 白色发光粗体):总结与展望
【左侧区域 — 项目总结(占宽 52%,占高 70%)】
四张半透明毛玻璃卡片(#FFFFFF 15% 透明度,白色边框),纵向排列:
卡片一(带星标图标):
标题(金色 #F59E0B 16pt):六大核心创新
正文(白色 13pt):AI 多角色深度融合 · 硬件软件全链路数据闭环 · 配置驱动通用实验框架 · 实时级联计算引擎 · 视觉化即时反馈 · 三种测量方法同平台对比
卡片二(带架构图标):
标题(金色 16pt):技术架构
正文(白色 13pt):Vue 3 + FastAPI 前后端分离 · Pydantic v2 ↔ TypeScript 双向类型对齐 · PyUSB 示波器直连 + 自动模拟回退 · REST + SSE 双通道 AI 通信
卡片三(带流程图标):
标题(金色 16pt):全流程教学闭环
正文(白色 13pt):预习(AI 助教 SSE 流式对话)→ 测验(AI 智能批改诊断)→ 实验(硬件采集 + AI 实时评价 + 级联计算 + PDF 导出)→ 考试 → 总结
卡片四(带拼图图标):
标题(金色 16pt):可复用性
正文(白色 13pt):任意物理实验仅需编写 JSON 配置文件即可接入平台 · 7 Sheet 80+ 单元格的声速实验已完整实现验证
【右侧区域 — 未来展望(占宽 40%,占高 70%)】
一张向上的成长曲线图(等距 3D 风格):
- 横轴标注时间线(现在 → 短期 → 中期 → 长期)
- 纵轴标注功能维度
- 四个台阶节点,每个节点处放置插图+文字:
台阶一(左下,已实现 ✅):
插图:当前项目截图缩影(表格 + AI 气泡)
文字:声速实验全流程(当前已完成)
台阶二(短期,蓝色上升箭头):
插图:摄像头对准游标卡尺,屏幕上显示 OCR 识别结果
文字:接入真实 OCR + 摄像头视觉识别
台阶三(中期,紫色上升箭头):
插图:三个不同实验的图标(拉伸机/电桥/干涉仪)从 JSON 文件"长出来"
文字:扩展至杨氏模量、惠斯通电桥、迈克尔逊干涉仪等
台阶四(长期,金色上升箭头):
插图:一个学生远程操作实验设备 + 一个 AI 大脑与实验设备双向交互
文字:WebSocket 远程实验 + 多模态 AI(图像+语音+手势)辅助操作
【底部信息行(距底边 60px)】
14pt 白色半透明文字居中:全国大学生物理实验竞赛 · AI+物理实验赛道 · AI+声速测量实验 团队
左侧放置超声波探头 + AI 芯片的组合图标(金色描边)。
【装饰】页号 "10" 左上角蓝色圆点,底部 2px 金色 #F59E0B 细线(末页特殊强调色)。
```
---
## 六、附录:关键文件索引
| 文件 | 路径 |
|------|------|
| 总体架构文档 | `docs/ARCHITECTURE.md` |
| 前端架构文档 | `frontend/ARCHITECTURE.md` |
| 后端架构文档 | `backend/ARCHITECTURE.md` |
| 实验配置 (JSON) | `backend/config/experiments/cn.edu.muc.lxy.phyexp.voicespeed.json` |
| 前端实验注册表 | `frontend/src/assets/experiences.json` |
| 前端类型定义 | `frontend/src/types/experiment.ts` |
| 后端 Pydantic 模型 | `backend/app/schemas/experiment.py` |
| Pinia 实验 Store | `frontend/src/stores/experiment.ts` |
| 级联计算引擎 | `frontend/src/utils/calculation.ts` |
| AI 客户端 | `frontend/src/utils/aiClient.ts` |
| AI 评价上下文 | `frontend/src/utils/aiEvalContext.ts` |
| 字段验证器 | `backend/app/core/validation.py` |
| 读数守卫 | `backend/app/core/reading_guard.py` |
| 峰值检测器 | `backend/app/core/peak_detector.py` |
| 示波器驱动 | `backend/app/hardware/oscilloscope.py` |
| 实验网格组件 | `frontend/src/components/experiment/ExperimentGridCell.vue` |
| AI 对话侧栏 | `frontend/src/components/AIChatSidebar.vue` |