---
title: "五劳无感康养监测系统 — 研发过程性材料"
subtitle: "过程记录 · 版本演进 · 关键问题修复"
version: V1.0（框架版，待补充图/视频）
date: 2026-08-26
author: 杨志佳
project: Healthv2.0
branch: main
git-head: 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 ✅ 已交付能力

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

```bash
# 烧录
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. 所有"⏳ 进行中"项，转交前请与甲方确认是否纳入正式交付范围。