ECG Ref 心电监护参考项目

ECG Ref 是一个用于心电采集、实时监护、历史回放和异常分析的参考项目。仓库同时包含 ESP32-S3 固件、PyQt 桌面端和浏览器 WebUI，适合用于本地调试、课堂演示、算法验证和采集流程原型。

本项目用于工程参考和信号处理实验，不应作为医疗诊断系统直接使用。

功能概览

• ESP32-S3 固件：读取 ECG 模拟输入，完成基础滤波、QRS 能量估计、R 峰检测、心率计算和串口输出。
• 桌面监护端：通过 PyQt 显示实时波形、指标卡、历史记录、统计图和异常事件。
• Web 监护端：通过本地 HTTP 服务打开浏览器界面，支持实时波形、异常摘要、历史回放和统计分析。
• 数据记录：会话数据保存为 CSV，窗口快照保存到 ecg_records/snapshots/。
• 性能优化：WebUI 的实时状态接口支持增量轮询，前端使用本地缓冲和 requestAnimationFrame 降低重绘成本。

项目结构

.
├── src/                  # ESP32-S3 / PlatformIO 固件
├── webui/                # 浏览器前端
├── tests/                # Python 单元测试
├── ecg_scope.py          # PyQt 桌面端入口
├── web_server.py         # WebUI 本地 HTTP 服务入口
├── ecg_*.py              # 共享模型、协议、记录、历史、分析和 UI 辅助模块
├── platformio.ini        # PlatformIO 固件配置
├── scope.bat             # 启动桌面端
└── webui.bat             # 启动 WebUI

运行时数据会写入 ecg_records/。该目录、.pio/ 和 __pycache__/ 已被 Git 忽略。

快速开始

1. 构建固件

pio run

目标板配置位于 platformio.ini，当前环境是 esp32-s3-devkitc-1，串口波特率为 115200。

2. 启动桌面端

.\scope.bat

桌面端会读取串口数据，显示实时 ECG 波形、QRS 能量、心率、导联状态和异常统计。

3. 启动 WebUI

.\webui.bat

然后打开：

http://localhost:5173/

WebUI 由 web_server.py 提供本地 API 和静态文件服务。

4. 回放历史 CSV

python web_server.py --input ecg_records\ecg_session_YYYYMMDD_HHMMSS.csv

默认会循环回放；如需播完停止：

python web_server.py --input ecg_records\ecg_session_YYYYMMDD_HHMMSS.csv --no-loop

串口协议

固件通过文本帧输出，当前桌面端和 WebUI 均保持兼容：

>S:index,raw,filtered,energy,leads_off
>HR:bpm
>Beats:count
>Threshold:value
>Beat:sample_id,energy,rr_ms
>Status:1

其中 >S: 是合并采样帧，包含采样编号、原始值、滤波后显示值、QRS 能量和导联脱落标记。

Web API

常用接口：

• GET /api/state：完整实时状态快照。
• GET /api/state?since=<sample_id>：只返回指定采样点之后的增量波形数据。
• GET /api/ports：列出可用串口。
• GET /api/history：列出历史 CSV。
• GET /api/history-data?path=<csv>：读取历史数据，服务端会下采样以适配浏览器绘制。
• GET /api/analyze?path=<csv>：分析历史异常事件和统计图数据。
• POST /api/connect、POST /api/disconnect、POST /api/config、POST /api/record/start、POST /api/record/stop、POST /api/clear、POST /api/snapshot。

增量状态响应包含：

{
  "series_delta": { "ids": [], "filtered": [], "energy": [] },
  "next_since": 12345,
  "reset": false
}

如果客户端游标过旧或服务端缓冲被清空，reset 会为 true，前端应重新同步完整状态。

验证

Python 语法检查建议使用内存编译方式，避免写入受权限影响的 __pycache__：

python -B -c "import pathlib; files=list(pathlib.Path('.').glob('*.py')) + list(pathlib.Path('tests').glob('*.py')); [compile(p.read_text(encoding='utf-8'), str(p), 'exec') for p in files]; print('ok')"

运行单元测试：

python -B -m unittest discover -s tests

固件构建：

pio run

English

ECG Ref is a reference project for ECG acquisition, real-time monitoring, history playback, and anomaly analysis. It includes ESP32-S3 firmware, a PyQt desktop monitor, and a browser-based WebUI.

This project is intended for engineering reference and signal-processing experiments. It is not a medical diagnostic system.

Highlights

• ESP32-S3 firmware reads ECG analog input, applies filtering, estimates QRS energy, detects beats, computes heart rate, and emits serial frames.
• The PyQt desktop app displays real-time waveforms, metric cards, history playback, statistics, and anomaly events.
• The WebUI serves a local browser dashboard with real-time monitoring, anomaly summaries, history playback, and statistical analysis.
• Session data is stored as CSV under ecg_records/; window snapshots are stored under ecg_records/snapshots/.
• The WebUI state endpoint supports incremental polling with ?since=<sample_id>, and the frontend uses a local buffer plus requestAnimationFrame for smoother rendering.

Quick Start

Build firmware:

pio run

Run desktop UI:

.\scope.bat

Run WebUI:

.\webui.bat

Open:

http://localhost:5173/

Replay a recorded CSV:

python web_server.py --input ecg_records\ecg_session_YYYYMMDD_HHMMSS.csv

Run tests:

python -B -m unittest discover -s tests

Repository Layout

• src/: ESP32-S3 firmware.
• webui/: browser frontend.
• ecg_scope.py: PyQt desktop entrypoint.
• web_server.py: local WebUI server and API entrypoint.
• ecg_*.py: shared models, protocol parsing, recording, history, analysis, and UI helpers.
• tests/: Python unit tests.