yangzhijia/health-wellness-device-2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
health-wellness-device-2/docs/研发过程性材料-框架.md
T

19 KiB
Raw Permalink Blame History

title, subtitle, version, date, author, project, branch, git-head
title subtitle version date author project branch git-head
五劳无感康养监测系统 — 研发过程性材料 过程记录 · 版本演进 · 关键问题修复 V1.0（框架版，待补充图/视频） 2026-08-26 杨志佳 Healthv2.0 main 7845836

五劳无感康养监测系统

研发过程性材料

本文档说明

  • 用途：面向甲方的研发过程性材料（验收/结项参考）。
  • 形式：简要版，约 5–10 页（Word A4）。
  • 状态：本版本为框架，各章节预留了图位、视频位与文字占位符。研发人员自行补图/视频/详细说明。
  • 图位标记：[📷 图片占位 — 描述] — 替换为 ![描述](相对路径)。
  • 视频位标记：[🎬 视频占位 — 描述] — 替换为 Word 中插入的视频；Markdown 阶段可保留占位符。
  • 代码/日志贴图位：[🖥 屏幕截图位 — 描述]。
  • 未提交/进行中标记：⏳ 标识。

目录

  1. 项目概述
  2. 系统架构与硬件组成
  3. 关键功能演示（视频位）
  4. 软件模块划分
  5. 版本演进（Git 历史）
  6. 关键 Bug 修复过程（案例）
  7. 测试与验证记录
  8. 当前已交付功能 / 待办

1. 项目概述

1.1 项目定位

【📝 占位 200–300 字。内容方向：】

  • 项目背景与甲方需求（一句话总结）
  • 设备形态：卫生间/卧室/客厅/阳台/厨房，挂壁式
  • "无感监测"理念：零穿戴、零接触、隐私优先（雷达不上传原始波形）

1.2 核心能力一览

维度 能力
生命安全 跌倒检测、生命体征异常（心率/呼吸）
环境安全 水浸、 温湿度异常
设备自检 雷达超时、 DHT11 故障
通信 MQTT V0.08 协议、WiFi 配网、蓝牙配网
联动 本地蜂鸣 + 远程告警、双向告警恢复
显示 OLED 多页显示（环境 / 体征 / 状态 / 报警）

1.3 技术指标（关键参数）

【📝 占位：列出关键阈值——心率 50–120 bpm、呼吸 10–26 次/分、温度 5–45℃、湿度 15–90% RH、上报周期 1s/60s 心跳、报警响应延迟 ≤ 20s】

1.4 项目实物图

【📷 图片占位 — 整机实物照片：外壳 + OLED 显示 + 雷达天线位 + 接线端子】

2. 系统架构与硬件组成

2.1 总体架构（ASCII）

                       ┌───────────────────────────┐
                       │      云端 MQTT 服务       │
                       │      202.110.234.102:8000 │
                       └─────────────┬─────────────┘
                                     │ (WiFi, MQTT V0.08)
                                     │
              ┌──────────────────────┴──────────────────────┐
              │          五劳无感康养监测终端 (本设备)         │
              │                                              │
              │   ┌─────────┐   ┌─────────┐   ┌──────────┐  │
              │   │ R60AFD1 │   │  DHT11  │   │ 水浸传感  │  │
              │   │ 60G雷达 │   │ 温湿度  │   │  GPIO45  │  │
              │   └────┬────┘   └────┬────┘   └────┬─────┘  │
              │        │UART2      │GPIO4         │GPIO45   │
              │   ┌────┴────────────┴─────────────┴──────┐  │
              │   │            ESP32-S3 (双核)            │  │
              │   │                                       │  │
              │   │  核心0: 雷达解析任务 (10ms)           │  │
              │   │  核心1: 主循环 / WiFi / MQTT / 报警    │  │
              │   └───┬─────┬─────┬─────┬─────┬─────┬───┘  │
              │       │     │     │     │     │     │      │
              │     蜂鸣   LED   OLED  按钮  WiFi  NTP    │
              │     GPIO21 GPIO9 I2C×2 3键  2.4G  阿里云  │
              └──────────────────────────────────────────────┘

2.2 硬件清单

模块 型号 接口 备注
MCU ESP32-S3-DevKitC-1 — 双核 240MHz, 8MB Flash, PSRAM
雷达 R60AFD1 60GHz 毫米波 UART2 (GPIO17/1, 115200) 跌倒/姿态精准型；卫生间用
温湿度 DHT11 GPIO4 单总线，2s 一次
水浸 单数字引脚 GPIO45 (INPUT_PULLUP) LOW=有水
蜂鸣器 有源蜂鸣器 GPIO21 PWM 预留，实际用 digitalWrite
报警 LED 红 GPIO9 按报警类型节奏闪烁
WiFi LED 蓝 GPIO8 状态指示
OLED SSD1306 128×64 I2C (GPIO15/16) 多页显示
配网按钮 微型轻触 GPIO0 / GPIO14 长按 3s
解除按钮 微型轻触 GPIO13 一键全解
翻页按钮 微型轻触 GPIO46 OLED 页面切换

2.3 接线图与实物

  • 【📷 图片占位 — 接线示意图（杜邦线 / 端子排）】
  • 【📷 图片占位 — PCB / 内部布局】
  • 【📷 图片占位 — 卫生间安装实景（雷达顶装）】

2.4 引脚定义速查

功能 GPIO 说明
雷达 RX 17 接雷达 TX
雷达 TX 1 接雷达 RX (调试用)
雷达 GPIO1/2 2 / 11 活跃/有人指示
DHT11 4 数据线
水浸 45 INPUT_PULLUP
蜂鸣器 21 OUTPUT
LED 报警 9 OUTPUT
LED WiFi 8 OUTPUT
OLED SDA/SCL 15 / 16 I2C
按钮：配网 0 / 14 长按 3s
按钮：解除 13 单击
按钮：翻页 46 单击

3. 关键功能演示（视频位）

每条功能一句要点 + 一个演示视频。视频由研发自拍。

# 功能 要点 视频
3.1 上电自检与启动 串口日志显示 "系统就绪" 【🎬 启动序列】
3.2 WiFi 配网（按键 / 远程 / 蓝牙） 三种配网方式演示 【🎬 三种配网】
3.3 OLED 多页切换 翻页按钮循环：环境/体征/状态/报警 【🎬 OLED 翻页】
3.4 MQTT 上下行 串口 + 服务端抓包联动 【🎬 MQTT 报文】
3.5 跌倒报警触发与解除 跌倒模拟 → 蜂鸣急促 → 一键解除 【🎬 跌倒报警】
3.6 心率/呼吸异常报警 阈值内/外对比 【🎬 体征异常】
3.7 水浸报警 模拟浸水（棉签沾水） 【🎬 水浸报警】
3.8 远程告警联动 服务端下发 → 设备蜂鸣 【🎬 远程告警】
3.9 远程告警恢复 服务端下发 → 蜂鸣停止 + 重武装 【🎬 远程恢复】

4. 软件模块划分

4.1 模块清单

模块 文件 职责
配置中心 include/config.h 全局宏、阈值、引脚、MQTT 默认参数
雷达 src/radar_manager.cpp UART 逐字节解析 + 防抖
传感器 src/sensor_manager.cpp DHT11 + 水浸采集、防抖
报警 src/alarm_manager.cpp 优先级管理、蜂鸣、LED
MQTT src/mqtt_manager.cpp 连接、订阅、上报、心跳
WiFi src/wifi_manager.cpp 连接、配网、WiFiManager
按钮 src/button_manager.cpp 去抖、单击/长按分发
OLED src/display_manager.cpp 多页渲染
主程序 src/main.cpp 主循环 + 本地报警判定

4.2 主循环流程（ASCII）

   ┌─────────────────────────────────┐
   │        loop() 核心1              │
   │  按钮 → WiFi → MQTT → 传感器    │
   │  → 本地报警检查 → 报警模块更新   │
   │  → 遥测上报 → OLED → 10ms delay │
   └──────────────┬──────────────────┘
                  │ 双核
   ┌──────────────┴──────────────────┐
   │    radarTask() 核心0             │
   │  10ms 周期: UART 字节流解析       │
   │  → 防抖 → 数据更新               │
   └─────────────────────────────────┘

4.3 报警优先级

优先级 类型 蜂鸣模式 LED 闪烁
★★★★★ 1 跌倒 急促连续哔（200/200ms） 200ms
★★★★★ 2 心率/呼吸异常 5连急哔 + 停顿 500ms
★★★ 3 水浸 3连哔 + 停顿 300ms
★★ 4 温湿度异常 2声长停 800ms
★ 5 传感器故障 单声长哔 1000ms

【🖥 屏幕截图位 — 串口日志演示报警触发】

5. 版本演进（Git 历史）

5.1 演进时间线

2026-07-22  init ───────────┐
                            ▼
2026-07-31  v1.0: 按钮去抖+配网美化+水浸离线+LED独立任务+
                    报警全拓展+有人才检测 ──┐
2026-08-06  版本1.2 ─────────────────────┤
2026-08-12  蓝牙配网 ─┐                 │
           ├ 修补 bug ┤ 配网完整化        │
           ├ 配编号   ┤                  │
           ├ 多设备烧 ┤                  │
           └ 清理 ai/ ┘─────────────────┤
                                         │
2026-08-14  阈值重整 + 跌倒时间消抖  ← 关键里程碑
2026-08-17  MQTT 重连修复 + 防抖层加入 + resident 字段还原
2026-08-18  跌倒 2 帧防抖 + 开机误报修复 ◀── 当前 HEAD (7845836)
            ⏳ 进行中: 蜂鸣静音开关（MUTE_VITAL_BUZZER）

5.2 关键 Commit 列表

SHA 日期 类型 标题 影响
49e3abb 07-22 feat init 项目初始骨架
69e927c 07-31 feat 按钮去抖+配网美化+水浸离线+LED独立任务+报警全拓展+有人才检测 v1.0 主要能力奠定
2ce4ac0 08-06 — 版本1.2 阶段化归档
93112dc 08-12 feat 增加蓝牙配网功能 配网多端支持
08a055b 08-12 fix 修补蓝牙配网bug —
36f5a28 08-12 feat 增加蓝牙配网设备编号 —
cc3ba5a 08-12 feat 增加多设备烧录 量产支撑
8facb8b 08-12 chore 忽略 ai/sessions/ 仓库瘦身
577eafd 08-14 init init 重整基线
9a4b5cf 08-14 fix/feat 跌倒时间消抖 + 修复误触发报警 误报收敛第一阶段
b960682 08-17 fix MQTT 断线重连 + 报警阈值修改 稳定性提升
03129c9 08-17 fix/feat resident 字段还原 + 增加防抖 误报收敛第二阶段
7845836 08-18 feat/fix 跌倒 2 帧防抖 + 修复开机错误跌倒报警 当前 HEAD

5.3 各版本能力差异

阶段 新增能力 已删除/替换
v1.0 4 类报警 → 7 类报警；LED 独立任务；有人才检测；离线水浸 —
v1.2 蓝牙配网多端、多设备烧录 —
v1.3 跌倒时间消抖、阈值下调、远程断线修复 部分阈值放宽
v1.4 防抖层（运动 3 帧、presence 8 帧） resident 误判修复
v1.5（当前） 跌倒 2 帧防抖 + 开机误报修复 —
⏳ 进行中 蜂鸣静音开关（MUTE_VITAL_BUZZER） 临时测试用，正常模式仍全开

6. 关键 Bug 修复过程（案例）

挑选 3–4 个最有代表性的真实案例，甲方最能感知的修复优先。

6.1 案例：跌倒开机误报

  • 现象：设备上电后即触发蜂鸣 + 上报 fall=1。
  • 根因：R60AFD1 雷达上电自检约 15–30s，期内 data[3] 的 fall 位为随机值。
  • 修复（双层防御）：
    • L1 时间跳过：checkLocalAlarms() 中 millis() > 30000 才进入跌倒判定。
    • L2 数据防抖：_filterFall() 连续 2 帧 fall=true 才置位。
  • 验证：实测快速坐下不报警；唯一跌倒模拟仍触发。
  • 变更文件：main.cpp（30s 跳过）、radar_manager.cpp/_filterFall（2 帧去抖）。

【🖥 屏幕截图位 — 开机 30s 内的串口日志 + 修复后日志对比】

【🎬 视频位 — 修复前后跌倒模拟对比】

6.2 案例：跌倒信号抖动 → 报警反复

  • 现象：跌倒持续中偶尔清掉，10s 后又触发，反复。
  • 根因：原 FALL_DETECT_MS 较紧，AFD1 fall 位信号不稳。
  • 修复：
    • 检测阶段：FALL_DETECT_MS = 10000（持续 10s 才触发）。
    • 清除阶段：FALL_CLEAR_MS = 18000（消失 18s 后才解除，防止误清）。
  • 变更文件：main.cpp 第 70–77 行宏定义、第 354–369 行清除逻辑。

【🖥 屏幕截图位 — 修复前后误报序列对比】

6.3 案例：MQTT 告警阈值调整（误报收敛）

  • 现象：心率偶发飙到 130+ 触发报警，用户无感。
  • 根因：原阈值过严，睡眠翻身等场景会让雷达瞬时给出异常心率。
  • 修复：
    • 心率放宽 → 50–120 bpm；呼吸 10–26 次/分。
    • 持续 20s 异常才触发，恢复 15s 才解除。
  • 副作用：阈值放宽后，需要配合"VITAL_LOST_MS = 60s 生命体征丢失判定"做兜底。
  • 变更文件：config.h、main.cpp。

6.4 案例：resident 字段误判（一波三折）

  • 现象：在床监测时人未离床，resident 出现 0/1 跳变。
  • 根因：睡眠帧 data[3] 的 bit 含义在 ABD1 与 AFD1 上不同；最初误把 ABD1 的 bit0 当 fall。
  • 修复：
    • ABD1：只取 bit1 为 resident，bit0 视为睡眠标志。
    • AFD1：bit0=fall、bit1=resident，二者都报 fall=true 时计数。
  • 教训：协议文档不严谨导致两次还原（一次"fix"反而误伤，又一次"fix"放开）。
  • 变更文件：radar_manager.cpp/_extractSleep，include/radar_manager.h。

【📷 图片占位 — 协议字段对比截图（AFD1 vs ABD1）】

6.5 案例 ⏳ 进行中：蜂鸣静音开关

  • 当前状态：未提交（修改 alarm_manager.h/.cpp）。
  • 背景：测试环境心率/呼吸异常频率高，希望保留状态/MQTT/LED 但屏蔽蜂鸣（避免误响）。
  • 方案：
    • 新增编译期宏 MUTE_VITAL_BUZZER = 1（默认测试模式）。
    • 新增 _shouldBuzz(t)：心率/呼吸返回 false，其余返回 true。
    • triggerLocal/clearLocal 蜂鸣开/关前过该判断。
  • 安全约束：跌倒/水浸仍必须响（保障人身安全），代码内注释硬性声明。
  • 预计提交：测试通过后改回 0 重烧，正式版恢复全蜂鸣。

7. 测试与验证记录

【📝 占位：以下各项填实际测试结果】

7.1 测试环境

项 内容
固件版本 v1.5（7845836） + ⏳ MUTE_VITAL_BUZZER
设备编号 【编号】
安装位置 【卫生间/卧室/客厅…】
测试时间 【起~止】

7.2 测试用例与结果

编号 用例 期望 实际 通过
TC-01 上电启动 30s 内不报警 30s 内无任何报警 【粘贴】 ✅/❌
TC-02 跌倒模拟触发 10s 内报 fall=1 【粘贴】 ✅/❌
TC-03 快速坐下不报警 坐下不报 fall 【粘贴】 ✅/❌
TC-04 心率 50bpm 持续 20s 触发 触发报警 【粘贴】 ✅/❌
TC-05 心率恢复 15s 解除 解除报警 【粘贴】 ✅/❌
TC-06 水浸触发（棉签沾水） 触发报警 【粘贴】 ✅/❌
TC-07 远程告警下发 蜂鸣 + LED 【粘贴】 ✅/❌
TC-08 远程告警恢复 蜂鸣停止 【粘贴】 ✅/❌
TC-09 MQTT 断线恢复 60s 内重连 【粘贴】 ✅/❌
TC-10 配网 3 种方式 全部成功 【粘贴】 ✅/❌

7.3 跑分 / 性能数据

【📝 占位：上报周期实测、内存占用、CPU 占用、MQTT 流量统计】

【🖥 屏幕截图位 — 性能面板】

8. 当前已交付功能 / 待办

8.1 ✅ 已交付能力

  • 7 类报警：跌倒 / 水浸 / 心率异常 / 呼吸异常 / 温度异常 / 湿度异常 / 传感器故障
  • 优先级蜂鸣 + LED 分级闪烁
  • 双核并行：核心 0 雷达 + 核心 1 主循环
  • MQTT V0.08 双向告警（含恢复）
  • 三种配网：按键 / 远程 / 蓝牙
  • OLED 多页显示
  • OTA-ready 分区表（默认 8MB）
  • 多设备烧录（upload_port 可配）

8.2 ⏳ 进行中 / 待办

  • ⏳ 提交 MUTE_VITAL_BUZZER 静音开关（测试用，正常版应改回 0）
  • 🕒 水浸「沾水不报警」根因待查 — 数字引脚 + INPUT_PULLUP 默认 HIGH（干），需要确认 env_type=bathroom 与水浸硬件接入；需用户提供浴室实机串口日志
  • 📋 文档：完整协议 V0.08 公开
  • 🛠 生产固件打包脚本

8.3 已知限制

项 限制 影响
R60AFD1 不发心跳/呼吸数据 心率呼吸类报警仅 ABD1 上有效
OLED 128×64 多行不可同屏 需要翻页
WiFi 2.4G only —
MQTT 仅支持一台设备一对一下发 多设备需扩展

附录 A：仓库与构建信息

  • 仓库：（公司内 Git 服务器）
  • 当前分支：main
  • HEAD Commit：7845836（feat：增加跌倒防抖帧 / fix：修复开机错误跌倒报警。）
  • 构建系统：PlatformIO + Arduino Framework
  • 板型：esp32-s3-devkitc-1
  • Flash 分区：default_8MB.csv
  • LittleFS：用于 WiFi / MQTT / 设备配置持久化
  • 第三方依赖（来自 platformio.ini）：
    • knolleary/PubSubClient@^2.8
    • bblanchon/ArduinoJson@^7.1.0
    • adafruit/DHT sensor library@^1.4.6
    • adafruit/Adafruit Unified Sensor@^1.1.14
    • olikraus/U8g2@^2.35.30

附录 B：变更与构建命令

# 烧录
pio run -t upload --upload-port COM19

# 监视
pio device monitor --port COM19 --baud 115200

# 清理
pio run -t clean

# 查看当前 git 差异（含未提交）
git diff HEAD

# 查看已提交历史
git log --oneline --graph --all

文档结束

填图/视频小贴士

  1. 每条 【📷 图片占位】 改成 ![说明](./images/abc.png)，图片统一放 docs/images/。
  2. 每条 【🎬 视频占位】 在 Markdown 阶段可用占位说明；转 Word 时手动插入"插入 → 联机视频"或本地 MP4。
  3. 每条 【🖥 屏幕截图位】 直接贴图，建议 1200×800 左右。
  4. 所有"⏳ 进行中"项，转交前请与甲方确认是否纳入正式交付范围。
Reference in New Issue View Git Blame Copy Permalink