xgen-waveform-viewer 是 X-GEN-LAB 归属的 PyQt6/pyqtgraph 桌面工具，用于通过 UART 串口实时查看 ADC 采样波形，支持多通道采集、自定义协议、固件配置和数据分析。
仓库归属：X-GEN-LAB 仓库命名：xgen-waveform-viewer
当前上位机版本：V3.0.0，内部语义化版本号：3.0.0。
- 支持最多 16 个独立 ADC 通道同时采集和显示
- 每通道独立配置：标签、颜色、可见性、Y 轴偏移
- 通道分组管理：按功能逻辑组织通道
- 配置持久化：自动保存和恢复通道设置
- 多协议支持：Binary V2（默认）、自定义二进制、ASCII 文本
- 自定义帧格式：通过 JSON 配置文件定义协议，无需修改代码
- 协议热切换：运行时切换协议，适配不同设备
- 内置模板：提供常用协议配置示例
- 版本管理：固件版本检测、兼容性检查
- 参数配置：远程配置采样率、帧长、通道、触发等参数
- OTA 更新：通过串口安全更新固件，实时进度显示
- 固件命令：14 种命令支持完整固件交互
- ✅ 实时串口读取 ADC 帧数据
- ✅ CRC-16-CCITT 帧校验
- ✅ 自动重同步与序列号间隙统计
- ✅ pyqtgraph 实时波形显示
- ✅ 支持命令行指定串口和波特率
- ✅ 支持保存和导出采样数据（BIN v2 / CSV）
- ✨ 配置持久化 - 自动保存和恢复用户设置
- ✨ 键盘快捷键 - 快速访问常用操作
- ✨ 主题切换 - 支持暗色/亮色主题
- ✨ 自动重连 - 串口断开后自动重新连接
- ✨ 菜单栏 - 更好的功能组织和访问
- 📏 测量工具
- 可拖动标尺：测量时间间隔和幅值差
- 峰值检测：自动识别并标注正负峰值
- 频率计算：基于峰值间隔自动计算频率
- 统计分析：RMS、平均值、最大最小值、峰峰值
- ⚡ 触发功能
- 多种触发模式：自动、正常、单次触发
- 多种触发类型：上升沿、下降沿、双边沿、电平触发
- 可配置阈值和滞回，有效抑制噪声
- 触发事件可视化和状态指示
- 🎬 录制增强
- 暂停/恢复：录制过程中可随时暂停
- 自动分段：按时间或文件大小自动分段
- 实时预览：显示录制时长、文件大小、帧数
- 🚀 性能优化
- Min/Max 降采样：高密度波形智能降采样，5-10x 性能提升
- 帧率限制：可配置 FPS 限制（1-120 FPS），降低 CPU 使用率 30-50%
- 内存管理：自动内存优化，防止系统内存耗尽
- 渲染优化：支持 >10 kHz 高采样率流畅渲染
- 🛡️ 鲁棒性提升
- 日志系统：完整的事件和错误日志记录
- 统计面板：实时数据完整性可视化
- 错误恢复：增强的 CRC 错误恢复策略
- 完整性检查：录制数据完整性验证
- 📼 数据回放
- 文件回放：支持 BIN 和 CSV 格式录制文件回放
- 变速播放：0.1x ~ 10x 可调播放速度
- 播放控制：播放、暂停、停止、恢复完整控制
- 进度显示：可视化播放进度条和时间显示
- 🎨 高级导出
- PNG 图片：导出当前可见波形为高清图片（1920x1080）
- SVG 矢量图：导出为可缩放矢量图形，适合出版
- MATLAB 格式：导出为 .mat 文件，科学计算标准格式
- HDF5 格式：高效压缩存储，节省 50-70% 空间
- HTML 报告：自动生成美观的统计报告，含波形图片
- 📊 波形比较
- 统计对比：比较两个波形的统计特性
- 差异分析：MSE、MAE、最大差异、相关性
- 🎯 多通道支持
- 最多 16 个独立通道同时采集
- 通道独立配置：标签、颜色、可见性、Y 轴设置
- 通道分组显示：按功能组织和管理
- 多通道数据缓冲区管理：每通道独立内存控制
- 通道配置持久化：JSON 格式保存和加载
- 🔧 协议扩展
- 多协议支持：Binary V2、Binary Custom、ASCII
- 自定义帧格式：JSON 配置文件定义协议
- 协议解析框架：可扩展的解析器架构
- 协议配置 UI：可视化编辑器
- 协议导入/导出：共享和复用配置
- 🚀 固件配置
- 固件版本检测：自动获取版本信息
- 参数配置：采样率、帧长、通道、触发
- OTA 更新：通过串口安全更新固件
- 兼容性检查：自动验证固件版本
- 固件命令协议：14 种命令类型
- 配置管理 UI：直观的配置面板
.
+-- src/
| +-- xgen_waveform_viewer/
| +-- __init__.py # 包初始化
| +-- __main__.py # 命令行入口
| +-- config.py # 配置常量
| +-- main.py # 程序入口
| +-- main_window.py # 主窗口（UI + 业务逻辑）
| +-- serial_reader.py # 串口读取线程
| +-- recorder.py # 数据录制线程
| +-- waveform_widget.py # 波形显示组件（V2.3：降采样支持）
| +-- measurement_tools.py # 测量工具（V2.2：标尺、峰值检测、统计）
| +-- trigger.py # 触发系统（V2.2：多种触发模式和类型）
| +-- performance.py # 性能优化（V2.3：降采样、内存管理）
| +-- logger.py # 日志系统（V2.3：事件和错误日志）
| +-- statistics_panel.py # 统计面板（V2.3：数据完整性可视化）
| +-- playback.py # 回放引擎（V2.4：数据回放核心）
| +-- playback_panel.py # 回放面板（V2.4：回放控制 UI）
| +-- exporter.py # 导出工具（V2.4：多格式导出）
| +-- settings.py # 配置持久化
| +-- theme.py # 主题管理
| +-- version.py # 版本信息
+-- docs/
| +-- RELEASE_NOTES_V2.1.md # V2.1 发布说明
| +-- RELEASE_NOTES_V2.2.md # V2.2 发布说明
| +-- RELEASE_NOTES_V2.3.md # V2.3 发布说明
| +-- RELEASE_NOTES_V2.4.md # V2.4 发布说明
+-- examples/
| +-- v2.2_measurement_example.py # V2.2 测量工具示例
| +-- v2.3_performance_example.py # V2.3 性能优化示例
| +-- v2.4_playback_and_export_example.py # V2.4 回放与导出示例
+-- .github/
| +-- workflows/
| +-- release.yml # 自动发布工作流
| +-- ISSUE_TEMPLATE/ # Issue 模板
| +-- PULL_REQUEST_TEMPLATE.md # PR 模板
+-- main.py # 开发环境入口（添加 src 到 path）
+-- xgen-waveform-viewer.spec # PyInstaller 打包配置
+-- pyproject.toml # 项目元数据（语义化版本 2.4.0）
+-- requirements.txt # Python 依赖
+-- README.md # 项目说明
+-- CHANGELOG.md # 版本更新日志
+-- ROADMAP.md # 开发路线图
+-- QUICKSTART.md # 快速入门指南
+-- CONTRIBUTING.md # 贡献指南
+-- LICENSE # MIT 许可证
+-- .gitignore
+-- release.ps1 # 发布脚本
+-- setup-dev.ps1 # 开发环境设置脚本
- Python 3.10 或更高版本
- Windows、Linux 或 macOS
- 可用的串口设备
创建虚拟环境：
python -m venv .venv
.\.venv\Scripts\Activate.ps1安装依赖：
pip install -r requirements.txt如果需要 MATLAB 和 HDF5 导出功能：
pip install -r requirements.txt
pip install scipy h5py或使用完整安装：
pip install -e ".[full]"从源码直接运行：
python main.py指定串口和波特率：
python main.py --port COM3 --baud 460800查看版本：
python main.py --version如果使用可编辑安装，也可以运行命令行入口：
pip install -e .
xgen-waveform-viewer --port COM3 --baud 460800| 快捷键 | 功能 |
|---|---|
Space |
恢复 X 轴自动滚动 (Follow) |
C |
连接/断开串口 |
R |
开始/停止录制 |
M |
切换标尺测量工具 🆕 V2.4.1 |
P |
检测并标注峰值 🆕 V2.4.1 |
Ctrl+P |
打开数据回放面板 |
Ctrl+T |
切换工具面板（测量+触发）🆕 V2.4.1 |
Ctrl+I |
打开统计面板 🆕 V2.4.1 |
F |
显示缓冲区全部数据 |
Y |
切换 Y 轴自动/手动模式 |
+ / - |
X 轴放大/缩小 |
Ctrl+S |
保存缓冲区到文件 |
Ctrl+E |
导出缓冲区为 CSV |
Ctrl+Q |
退出应用 |
鼠标操作：
- 左键拖拽：平移视图
- 滚轮：缩放
- 双击：恢复自动滚动
应用会自动保存以下设置：
- 串口配置（最后使用的端口、波特率等）
- 显示设置（X/Y 轴范围、缓冲区大小、主题）
- 录制设置（格式、保存目录）
- 窗口大小和位置
配置文件位置：
- Windows:
%APPDATA%\X-GEN-LAB\xgen-waveform-viewer.ini - Linux:
~/.config/X-GEN-LAB/xgen-waveform-viewer.conf - macOS:
~/Library/Preferences/com.X-GEN-LAB.xgen-waveform-viewer.plist
当前解析器按以下 UART 帧格式读取数据：
[SYNC0=0xA5][SYNC1=0x5A] 2 bytes
[SEQ] uint32 little-endian
[SAMPLES_CNT] uint16 little-endian
[SAMPLES] SAMPLES_CNT * uint16 little-endian
[CRC16] CRC-16-CCITT, covers SEQ + SAMPLES_CNT + SAMPLES
默认参数在 src/xgen_waveform_viewer/config.py 中配置。
项目保留了 PyInstaller spec 文件。安装 PyInstaller 后可执行：
pip install pyinstaller
pyinstaller xgen-waveform-viewer.spec生成文件会输出到 dist/，该目录不会提交到 Git。
仓库包含 .github/workflows/release.yml。推送形如 V2.0 或 v2.0.0 的 Git 标签后，GitHub Actions 会自动：
- 在 Windows runner 上安装 Python 依赖
- 运行
python -m compileall src main.py - 使用 PyInstaller 构建
xgen-waveform-viewer.exe - 打包 zip 文件并生成 SHA256 校验文件
- 创建或更新对应 GitHub Release
发布新版本：
git add .
git commit -m "chore: prepare release workflow"
git tag V2.0
git push origin main
git push origin V2.0也可以在 GitHub 页面进入 Actions -> Release -> Run workflow 手动输入版本号触发。
版本号约定：
- 对外显示版本使用
V主版本.次版本，例如V2.1 - 代码和包元数据使用完整语义化版本
主版本.次版本.修订号，例如2.1.0 - 修复问题但不改变功能：
2.1.1 - 新增兼容功能：
2.2.0 - 不兼容升级：
3.0.0
详见 CHANGELOG.md。
本项目使用 MIT License，版权归属为 X-GEN-LAB。详见 LICENSE。