# 新人项目训练任务书

## 目录

- [一、训练目的](#一训练目的)
- [二、硬件与开发环境](#二硬件与开发环境)
  - [2.1 硬件](#21-硬件)
  - [2.2 接线](#22-接线)
  - [2.3 开发环境](#23-开发环境)
  - [2.4 需自行查阅的资料](#24-需自行查阅的资料)
- [三、通用要求](#三通用要求)
- [四、任务一：雷达串口数据采集并打印到串口 0](#四任务一雷达串口数据采集并打印到串口-0)
  - [4.1 任务目标](#41-任务目标)
  - [4.2 功能需求](#42-功能需求)
  - [4.3 完成标准](#43-完成标准)
- [五、任务二：引入实时操作系统并新增蓝牙数据传输任务](#五任务二引入实时操作系统并新增蓝牙数据传输任务)
  - [5.1 任务目标](#51-任务目标)
  - [5.2 功能需求](#52-功能需求)
  - [5.3 完成标准](#53-完成标准)
- [六、任务三：新增蓝牙配网任务](#六任务三新增蓝牙配网任务)
  - [6.1 任务目标](#61-任务目标)
  - [6.2 功能需求](#62-功能需求)
  - [6.3 完成标准](#63-完成标准)
- [七、任务四：WiFi 配置持久化与开机自动重连](#七任务四wifi-配置持久化与开机自动重连)
  - [7.1 任务目标](#71-任务目标)
  - [7.2 功能需求](#72-功能需求)
  - [7.3 完成标准](#73-完成标准)
- [八、训练建议](#八训练建议)
- [附录 A：雷达串口通信协议](#附录-a雷达串口通信协议)
  - [A.1 物理层](#a1-物理层)
  - [A.2 帧格式](#a2-帧格式)
  - [A.3 控制字与数据项](#a3-控制字与数据项)
  - [A.4 主控命令帧](#a4-主控命令帧)
  - [A.5 常用命令示例](#a5-常用命令示例)
- [附录 B：蓝牙通信协议](#附录-b蓝牙通信协议)

---

## 一、训练目的

围绕"雷达数据采集 → 蓝牙数据传输 → 蓝牙配网 → 配置持久化"这一典型物联网设备开发场景，由浅入深完成四个任务，使学员掌握：

- 串口（UART）数据采集与二进制协议解析；
- 实时操作系统（FreeRTOS）下的多任务设计与任务间通信；
- 蓝牙（BLE）GATT 通信与二进制协议实现；
- 设备联网配置（扫描、连接、持久化、状态反馈）。

四个任务循序渐进，后一个任务在前一个任务的基础上扩展：

```
任务一：串口数据采集打印      任务二：RTOS 多任务 + 蓝牙数据传输      任务三：蓝牙配网          任务四：配置持久化 + 开机自动重连
雷达 ─UART─▶ 串口0 打印       采集任务 ─队列─▶ 蓝牙发送任务           扫描 / 连接 WiFi          Flash 存储 ─▶ 复位自动重连
```

## 二、硬件与开发环境

### 2.1 硬件

| 项目 | 说明 |
| --- | --- |
| 主控 | ESP32-S3（Freenove ESP32-S3 WROOM，N8R8：8MB Flash / 8MB PSRAM） |
| 传感器 | R60ABD1 毫米波雷达模组（UART 接口） |
| 调试 | USB 数据线连接电脑，作为串口 0 使用 |

### 2.2 接线

| 雷达模组 | ESP32-S3 | 说明 |
| --- | --- | --- |
| TX | 任意可用 RX 引脚 | 主控接收 |
| RX | 任意可用 TX 引脚 | 主控发送 |
| GND | GND | 必须共地 |
| VCC | 按模组手册供电 | 注意电压与电流要求 |

> 具体引脚、波特率、数据位/停止位/校验位以雷达模组数据手册和训练方要求为准。

### 2.3 开发环境

- VS Code + PlatformIO（或 Arduino IDE，按训练方统一要求）；
- 串口调试助手（用于查看串口 0 输出）；
- 蓝牙调试 App（如 nRF Connect）或微信小程序蓝牙调试工具。

### 2.4 需自行查阅的资料

- ESP32-S3 技术参考手册、Arduino-ESP32 / ESP-IDF 官方文档；
- FreeRTOS 官方文档；
- 蓝牙 GATT 规范及 ESP32 蓝牙例程；
- 本任务书 [**附录 A：雷达串口通信协议**](#附录-a雷达串口通信协议) 与 [**附录 B：蓝牙通信协议**](#附录-b蓝牙通信协议)（学员须严格按协议实现）。

## 三、通用要求

1. **独立完成**：禁止直接复制他人代码，须能独立说明实现原理。
2. **代码质量**：结构清晰、命名规范、注释完整，保证可编译、可烧录。
3. **稳定性**：长时间运行不崩溃、不丢帧、不阻塞、不触发看门狗复位。

## 四、任务一：雷达串口数据采集并打印到串口 0

### 4.1 任务目标

搭建最小工程，从雷达串口读取数据，完成组帧与校验，并通过串口 0（USB 调试口）把数据打印到电脑上。

### 4.2 功能需求

1. 正确初始化调试串口与雷达串口，串口参数依据雷达数据手册设置。
2. 从雷达串口接收字节流，依据 [**附录 A 雷达串口通信协议**](#附录-a雷达串口通信协议) 对字节流进行**组帧**。
3. 对每个完整帧进行**校验**，校验失败的帧必须丢弃并给出提示。
4. 通过串口 0 打印**人类可读的关键信息**：解析帧内容后，按字段输出人体存在、运动状态、距离、坐标、心率、呼吸、睡眠等信息（字段定义见 [附录 A](#附录-a雷达串口通信协议)），要求信息清晰、易于查看。
5. 雷达模组上电后不会主动上报，需按 [附录 A](#附录-a雷达串口通信协议) 发送使能命令后才输出数据；需实现命令帧的构造与发送（含校验和计算）。
6. 程序运行稳定，接收过程不阻塞、不丢帧，缓冲区溢出时能自动恢复。

### 4.3 完成标准

- [ ] 串口 0 能稳定输出人类可读的解析结果，字段含义正确、无乱码。
- [ ] 人体靠近/远离时，能观察到数据实时变化。
- [ ] 人为构造校验错误的帧，程序能识别并丢弃。
- [ ] 能清晰说明 [附录 A](#附录-a雷达串口通信协议) 的帧格式、校验算法与字段布局。

## 五、任务二：引入实时操作系统并新增蓝牙数据传输任务

### 5.1 任务目标

将任务一改造成基于实时操作系统（FreeRTOS）的多任务架构，并新增一个蓝牙数据传输任务，把采集到的雷达数据按 [**附录 B 蓝牙通信协议**](#附录-b蓝牙通信协议) 发送给手机端。

### 5.2 功能需求

1. **任务化改造**：引入 FreeRTOS，把任务一的"串口采集 + 组帧 + 解析"实现为一个独立任务。
2. **新增蓝牙数据传输任务**：负责蓝牙初始化、服务与特征定义、数据收发。
3. **任务解耦**：采集任务与蓝牙任务之间通过队列（或等效机制）传递数据，禁止跨任务直接读写共享变量；共享资源的访问须加互斥保护。
4. **蓝牙需提供两类通道**：
   - **数据通知通道**：周期性或在数据变化时向手机推送雷达数据；
   - **命令通道**：接收手机写入的命令，并按命令返回对应响应。
5. **命令功能**：至少支持"启动连续推送""停止连续推送""查询一次数据"，并对未知命令返回错误响应。
6. **按 [附录 B](#附录-b蓝牙通信协议) 实现蓝牙传输协议**：严格按协议规定的 GATT 服务/特征、帧格式、TLV 编码、命令码、错误码实现；要求：
   - 发送端支持**分包**，接收端支持**重组**；
   - 命令响应与请求通过序列号**一一对应**；
   - 接收端校验 CRC 并丢弃非法帧。
7. **健壮性**：发送需做互斥与必要的节流；断开连接后停止推送，重连后按客户端命令恢复。

### 5.3 完成标准

- [ ] 手机端订阅通知特征后，能稳定收到可解析的雷达数据帧，内容随人体状态变化。
- [ ] 手机端写入查询命令，能收到匹配的响应（序列号一致、校验正确）。
- [ ] 启动 / 停止连续推送命令均生效；未知命令返回错误响应。
- [ ] 多任务运行稳定，无明显阻塞与看门狗复位。
- [ ] 能说明任务划分、队列/互斥设计，以及 [附录 B](#附录-b蓝牙通信协议) 协议的实现要点。

## 六、任务三：新增蓝牙配网任务

### 6.1 任务目标

在任务二基础上，新增一个蓝牙配网任务，按 [**附录 B 蓝牙通信协议**](#附录-b蓝牙通信协议) 的配网命令，实现通过手机蓝牙下发 WiFi 信息，使设备完成联网。

### 6.2 功能需求

1. **新增独立配网任务**：处理手机下发的配网相关命令，耗时的 WiFi 操作不得放在蓝牙回调中执行。
2. **WiFi 扫描**：扫描附近 WiFi，并返回网络列表（名称、信号强度、加密类型）。
3. **WiFi 配网**：
   - 接收手机下发的 SSID 与密码；
   - 尝试连接目标网络；
   - 向手机反馈结果：成功（含获取到的 IP）或失败及失败原因。
4. **异步反馈**：配网为异步过程，收到命令后先回"处理中"，完成后再回最终结果。
5. **状态推送**：WiFi 连接中 / 已连接 / 断开 / 失败等状态变化时，主动向手机推送状态（仅在变化时推送）。
6. **错误处理**：对找不到目标网络、密码错误、信号过弱、设备忙等场景返回明确错误。
7. **并发安全**：配网期间避免与其它 WiFi 操作（如扫描、自动重连）冲突。
8. **联网校时**：WiFi 连接成功后，通过 NTP 获取当前时间，按北京时间（UTC+8）格式化后打印到串口。

### 6.3 完成标准

- [ ] 手机下发 SSID/密码后，先收到"处理中"，连接成功后收到成功结果与 IP；失败时收到对应错误。
- [ ] 能返回扫描到的 WiFi 列表（名称 / 信号强度 / 加密类型）。
- [ ] WiFi 状态变化时手机端能收到状态推送。
- [ ] 蓝牙回调不被耗时操作阻塞，配网过程可稳定完成。
- [ ] WiFi 连接成功后，串口能打印出正确的北京时间（UTC+8，格式如 `2026-09-11 17:00:00`）。

## 七、任务四：WiFi 配置持久化与开机自动重连

### 7.1 任务目标

在任务三的基础上，把配网成功的 WiFi 信息保存到 Flash，使设备复位或断电重启后能自动扫描并连接已保存的 WiFi。

### 7.2 功能需求

1. **配置持久化**：配网成功后，将 SSID 与密码保存到 Flash，掉电不丢失。
2. **多网络保存**：支持保存多个 WiFi 配置，并能查询、删除已保存的网络（按训练方要求）。
3. **开机自动重连**：设备复位或上电后，读取 Flash 中已保存的 WiFi 配置，自动扫描并连接可用网络，无需重新配网。
4. **选择与重试**：存在多个已保存网络时，按信号强度或保存顺序选择合适的网络连接；连接失败按一定间隔自动重试。
5. **状态反馈**：自动重连过程中，通过 [附录 B](#附录-b蓝牙通信协议) 的状态推送通道向手机反馈 WiFi 状态变化。
6. **容错**：Flash 无配置或全部连接失败时，保持可被蓝牙配网的状态，且不阻塞其它功能。

### 7.3 完成标准

- [ ] 配网成功后配置写入 Flash，断电 / 复位后仍然存在。
- [ ] 复位后设备自动扫描并连接已保存的 WiFi，无需重新配网。
- [ ] 保存多个网络时能正确选择并连接可用网络。
- [ ] 连接失败能自动重试，且不阻塞其它功能。
- [ ] 能说明 Flash 存储结构与开机自动重连流程。

## 八、训练建议

1. 每个任务先画数据流图 / 时序图、先定协议再编码，便于自测。
2. 雷达数据可先确认帧结构与校验正确，再实现字段解析与打印。
3. 多任务开发时先明确"谁生产、谁消费、如何同步"，再动手写代码。
4. 蓝牙通信建议使用调试 App 观察原始字节，确认分包与重组正确。
5. 养成记录调试过程的习惯：现象 → 定位 → 原因 → 解决，便于复盘。

---

## 附录 A：雷达串口通信协议

### A.1 物理层

| 参数 | 值 |
| --- | --- |
| 波特率 | 115200 |
| 数据位 / 停止位 / 校验 | 8 / 1 / 无（8N1） |
| 通信方式 | 主控下发命令 + 雷达主动上报 |

### A.2 帧格式

雷达与主控之间所有数据均采用如下格式，多字节字段均为**大端**：

```
53 59 | CTRL | CMD | LEN_H LEN_L | DATA... | CHECKSUM | 54 43
```

| 字段 | 长度 | 说明 |
| --- | --- | --- |
| 帧头 | 2 | 固定 `0x53 0x59` |
| CTRL 控制字 | 1 | 数据类别（人体存在 / 呼吸 / 心率 / 睡眠） |
| CMD 命令字 | 1 | 具体数据项；上报帧中最高位置 1（如 `0x03` 与 `0x83` 同义） |
| LEN | 2 | DATA 长度，大端 |
| DATA | N | 数据域 |
| CHECKSUM | 1 | 校验和 |
| 帧尾 | 2 | 固定 `0x54 0x43` |

**校验和**：从帧头第一个字节（`0x53`）累加到 DATA 最后一个字节，取累加和低 8 位，即：

```
CHECKSUM = (sum(frame[0] .. frame[帧长-4])) & 0xFF      // 位于 frame[帧长-3]
```

### A.3 控制字与数据项

**CTRL = 0x80（人体存在）**

| CMD | DATA | 含义 |
| --- | --- | --- |
| `0x00` / `0x80` | 1B | 开关上报，`0x01` 为开启 |
| `0x01` | 1B | 人体存在：`0` 无人 / `1` 有人 |
| `0x02` | 1B | 运动状态：`0` 无 / `1` 静止 / `2` 活跃 |
| `0x03` | 1B | 体动参数（0~100） |
| `0x04` | 2B | 人体距离（cm） |
| `0x05` | 6B | 坐标 X / Y / Z，各 2B；每值最高位为符号位（1 表示负） |

**CTRL = 0x81（呼吸）**

| CMD | DATA | 含义 |
| --- | --- | --- |
| `0x00` / `0x80` | 1B | 开关上报 |
| `0x01` | 1B | 呼吸状态 |
| `0x02` | 1B | 呼吸率（次/分） |
| `0x05` | 5B | 呼吸波形，实际值 = 字节值 − 128 |

**CTRL = 0x85（心率）**

| CMD | DATA | 含义 |
| --- | --- | --- |
| `0x00` / `0x80` | 1B | 开关上报 |
| `0x02` | 1B | 心率（BPM） |
| `0x05` | 5B | 心跳波形，实际值 = 字节值 − 128 |

**CTRL = 0x84（睡眠）**

| CMD | DATA | 含义 |
| --- | --- | --- |
| `0x00` / `0x80` | 1B | 开关上报 |
| `0x01` / `0x81` | 1B | 床状态（入床 / 离床） |
| `0x03` / `0x83` | 2B | 清醒时长 |
| `0x04` / `0x84` | 2B | 浅睡时长 |
| `0x05` / `0x85` | 2B | 深睡时长 |
| `0x06` / `0x86` | 1B | 睡眠评分 |
| `0x0C` / `0x8D` | 8B | 综合状态：存在(1)、睡眠状态(1)、平均呼吸(1)、平均心率(1)、翻身次数(1)、大幅运动比例(1)、小幅运动比例(1)、呼吸暂停次数(1) |
| `0x0D` / `0x8F` | 12B | 睡眠统计：评分(1)、总睡眠时长(2)、清醒比例(1)、浅睡比例(1)、深睡比例(1)、离床时间(1)、翻身计数(1)、翻身次数(1)、平均呼吸(1)、平均心率(1)、呼吸暂停次数(1) |
| `0x0E` / `0x8E` | 1B | 异常状态 |
| `0x10` / `0x90` | 1B | 睡眠等级 |
| `0x11` / `0x91` | 1B | 挣扎报警 |
| `0x12` / `0x92` | 1B | 无人报警 |

### A.4 主控命令帧

命令帧固定为 10 字节：

```
53 59 | CTRL | CMD | 00 01 | VALUE | CHECKSUM | 54 43
```

- LEN 固定为 `0x0001`，DATA 为 1 字节 `VALUE`。
- CHECKSUM 为前 7 字节的累加和低 8 位。

### A.5 常用命令示例

| 作用 | 命令帧（HEX） |
| --- | --- |
| 使能人体存在上报 | `53 59 80 00 00 01 01 2E 54 43` |
| 使能呼吸上报 | `53 59 81 00 00 01 01 2F 54 43` |
| 使能心率上报 | `53 59 85 00 00 01 01 33 54 43` |
| 使能睡眠上报 | `53 59 84 00 00 01 01 32 54 43` |
| 查询人体存在 | `53 59 80 80 00 01 0F BC 54 43` |

> 控制字、命令字与参数含义最终以雷达模组手册为准；上表为按本协议规则推导的示例，学员须自行验证。

---

## 附录 B：蓝牙通信协议

蓝牙通信协议（GATT 服务与特征、帧格式、TLV 编码、命令码、结果码、状态码、主动推送、客户端接入要求等）统一见同目录文档：

### [`蓝牙通信协议.md`](蓝牙通信协议.md)

本文不再重复协议细节，实现时以上述文档为准。