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

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

查看文件

@ -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)