# mothercup（母乳杯）设计说明书

V1.0 / 2026-09-05

本文整合当前系统的架构、协议、约定与扩展指南，供后续功能扩展时查阅。
细则以 `docs/ble_protocol.md`（协议权威）、`docs/开发日志.md`（踩坑根因）、
`AGENTS.md`（工程约定）为准；本文是三者 + 真机联调经验的汇总索引。

---

## 1. 系统组成

```
┌─────────────┐   BLE (GATT)    ┌──────────────────────┐
│ 手机 App     │ ◄─────────────► │ 设备 N32WB031        │
│ SmartAssiter│                 │  Boot + 双bank APP   │
└─────────────┘                 │  USART1 (PB6/PB7)    │
┌─────────────┐   BLE / UART    │   ↑                  │
│ PC 工具      │ ◄─────────────► │   └─ SWD (PA4/PA5)   │
│ tools/      │                 └──────────────────────┘
└─────────────┘
```

| 端 | 位置 | 技术栈 | 职责 |
|---|---|---|---|
| Bootloader | `Boot/` | C / ARMCC / 16KB @0x01000000 | 校验 bootsetting 记录 → 按 active bank 跳转 |
| 应用固件 | `mcm-ddc-ble/` | C / FreeRTOS V9.0.0 原生 API | BLE GATT 服务、CLI、参数、OTA |
| 手机 App | `SmartAssiter/` | uni-app Vue3 + TS（HBuilderX 工程） | 参数展示、CLI 终端、参数读写、OTA |
| PC 工具 | `tools/` | Python（无三方依赖的出包脚本 + bleak/pyserial 测试客户端） | 出包、烧录、OTA/CLI 参考实现 |

厂商 SDK/PDF 在 `nations-tec/`（**只读**）。SDK 源码经相对路径被工程引用，
各工程目录不能脱离仓库根单独移动。

## 2. 硬件平台与资源约束

- SoC：国民技术 N32WB031（板载硅片实测 **256KB Flash**，Cortex-M0 64MHz，
  RAM 48KB+16KB）
- **RAM 铁律**：低 16KB（0x20000000~0x20003FFF）被芯片 ROM/BLE 子系统占用，
  任何工程 IRAM 执行区必须从 **0x20004000** 起（否则 BLE init 必 HardFault）
- **SWD 引脚 SWCLK=PA4 / SWDIO=PA5，应用程序绝对禁止占用**
- 板载 LED：LED1=PB0、LED2=PA6；USART1：TX=PB6 / RX=PB7（AF4，115200 8N1）
- 新增 GPIO 前核对开发日志 §4 引脚分配表
- **不要直接写寄存器**；勘误修复必须先在 SDK 源码交叉验证地址用途
  （曾按勘误表写 AFEC 寄存器导致 BLE 射频挂死，开发日志 §28）

## 3. Flash 布局与启动

| 区域 | 地址 | 大小 | 说明 |
|---|---|---|---|
| Bootloader | 0x01000000 | 16KB | 只校验 bootsetting 记录自身（magic+CRC32）后跳转 |
| bootsetting | 0x01004000 | 8KB | active bank、双 bank 的 addr/size/crc32/version |
| APP_DATA | 0x01006000 | 8KB | 区头 `caiic_params_t` 参数记录（magic `0xCA12DA7A`+CRC32） |
| APP1 | 0x01008000 | 112KB | bank1 |
| APP2 | 0x01024000 | 112KB | bank2 |

- Boot **不校验镜像 CRC**（CRC 在 OTA 过程中完成）；记录无效/地址越界回退 APP1
- **VTOR**：Cortex-M0 无 SCB->VTOR，用 `PWR->VTOR_REG`。BLE init 前指向 APP 自身
  向量表（`0x80000000|0x01008000`）；`ns_ble_stack_init()` 之后必须为 0，
  **绝对不要在 BLE init 后重设 VTOR**（开发日志 §18）
- 固件不接 ns_sleep 低功耗（与 FreeRTOS tick 冲突），main 里永久锁睡眠保 SWD

## 4. 版本号与出包约定

- **每改固件必递增** `mcm-ddc-ble/inc/app_version.h` 的 `APP_FW_VERSION` /
  `APP_FW_VERSION_NUM`（`0x00MMmmpp`，补丁位 +1）
- 构建：Keil µVision5（ARMCC V5.06u6），要求 **0 Error 0 Warning**
- **出包必须 `UV4 -r` 全量重建**（增量构建产生过砖包，开发日志 §24），
  一键 `tools\make_package.bat`，产物在 `tools/out/`：
  - `mothercup_ble_prod.hex/.bin` — 生产整片包（Boot + 缺省 bootsetting + APP1）
  - `mothercup_ble_ota.bin` — OTA 发布单文件（52B 头 + 双 bank 载荷，格式见
    ble_protocol.md §7）
- 烧录：`tools\flash_package.bat`（NSpyocd 整片）；Keil 调试下载必须
  **Erase Sectors**（整片擦除会杀掉 Boot）
- `merge_image.py` 手动调用必须显式传参（默认路径指向已删除的旧工程）

## 5. BLE 接口（详见 ble_protocol.md §1/§2/§5）

广播名 `CAIIC-MCM-20260902`；服务 `00002760-08C2-11E1-9073-0E8AC72E1001`：

| 特征尾段 | 属性 | 通道定位 |
|---|---|---|
| e0001 | Write NoRsp | 帧协议下行（0xCA 字节流） |
| e0002 | Notify | 帧协议上行（V1.00.19 修复后可用） |
| e0003 | Read+Write | **CLI 通道**：写命令行(≤63B) → 分包读回文本（0 长度包=结束，上限 1024B） |
| e0004 | Read | **参数通道**：全信息项 TLV（同 INFO_RSP all） |
| e0005 | Read+Write | **OTA 通道**：写一传输帧 → 轮询读回 OTA_RSP（至非空） |

- MTU：连接后设备主动发起 247 交换；单次写入上限 = att_mtu − 3
- 帧格式：`CA | TYPE | SEQ | LEN(LE16) | PAYLOAD | CRC16-CCITT(LE)`，
  **CRC 覆盖 TYPE..PAYLOAD 共 4+payLen 字节**（新旧实现必须统一）
- 信息项：0x01 版本 / 0x02 温度(0.1℃) / 0x03 风扇 / 0x04 电压(mV) /
  0x05 运行时长(s) / 0x06 堆剩余(B) / 0x07 当前 bank（OTA 选包依据）

## 6. CLI 命令集（UART 与 BLE e0003 完全一致）

`help / version / sysinfo / devinfo / blelog / led / appget [json] /
appset / bsdump / bsset / appsw [1|2] / ota / reset / factory / uartrst / uartinfo`

- 维护区（bootsetting / APP_DATA）**只暴露结构化命令，无裸读写**
- `appsw` 切 bank 前校验目标镜像 CRC 与记录一致，不匹配拒绝
- `ota` 命令使 UART 进入二进制 OTA 模式（握手标记行 `[ota] binary mode ON`）
- `reset`/`factory`/`appsw` 均先应答、延时后复位（保证应答送达）

## 7. OTA 设计（详见 ble_protocol.md §6/§6.6/§7）

- **双 bank 直写**，无中转区；惰性擦扇区；仅 4B 对齐暂存
- **传输层通道无关**：同一 0xCA 帧会话（BEGIN/DATA/END/ABORT → OTA_RSP）
  可跑在 BLE e0005 / UART 二进制模式 / 旧帧协议通道；设备侧 OTA 引擎经
  通道注册的 sink 出口应答，会话全程只允许一个通道占用
- **逐帧锁步**：每帧等 ack（ack.offset = 设备期望的下一字节）；ack 超时直接
  重发同一帧（≤3 次）；重复帧回 BAD_STATE+期望 offset，恰好等于本帧结束位置
  则视为 ack（丢 ack 容错）；status=2 按其 offset 重发即再同步
- **END 可靠送达**（V1.00.20）：设备先发 ok 应答，等主机取走 + 300ms 宽限
  才复位，2s 兜底
- **选包规则**：读 CUR_BANK → 目标 = 对侧 bank → 从头取对应载荷；三重防呆：
  客户端向量表预检 + 固件 OTA_END bank_mismatch(status=6) + `appsw` CRC 校验
- 主机兜底：END 应答丢失不等于失败，复位后重连复核 CUR_BANK+FW_VERSION 定论

## 8. 手机 App 设计（SmartAssiter）

### 8.1 分层

```
pages/                页面（home / ota / my / bleTest 终端 / 云端账号页）
src/mcm/              设备业务层（只碰业务，不碰 BLE 细节）
  McmCli.ts           CLI 通道（Promise 链串行；写命令→分包读回）
  McmInfo.ts          参数通道（TLV 解析，含 CUR_BANK）
  McmOta.ts           OTA 通道（combo 包解析 + 锁步会话 + 重发/再同步/中止）
  McmCommands.ts      业务命令封装（sysinfo/devinfo/appget/appset…）
src/BluetoothManager.ts  蓝牙管理（扫描/连接/服务发现/读写/MTU）
common/  api/         token、已连设备记忆、云端 HTTP
```

### 8.2 通道隔离约定（重要）

- **每个特征值一条独立通道**：读请求按 UUID 分键排队/超时（3s）/分发；
  写无跨特征阻塞；CLI 与参数轮询与 OTA 可并行，一路故障不扩散
- 安卓兼容（实测踩坑）：服务发现后 300ms 稳定期；读/写被误报
  10007 "property not support" 时各延时 1600ms 重试一次；连接初始化
  **先 setMtu 再发起读写**（并发 GATT 操作会被安卓无声丢弃）
- home 页参数轮询由 **Auto refresh 开关**控制，**缺省关闭**（避免干扰 OTA）
- App 侧错误码：0 成功；10000 连接失败；10001 断开；10002 蓝牙未开；
  10003 无权限；10004/10005 服务/特征缺失；10008 读写/MTU/超时

### 8.3 OTA 页文件读取（Android 10+ 分区存储）

- `/sdcard/Download` 直读被禁（targetSdk≥29）；`uni.chooseFile` App 端不存在
- 现行方案：**SAF 选择器**（plus.android `ACTION_GET_CONTENT`，免权限）→
  ContentResolver 流 → Scanner 整流读 String（ISO-8859-1 字节 1:1）→
  **magic 自验**，不过则自动逐字节 `read()` 直读（二进制精确兜底）
- plus 桥注意：**byte[] 参数按值拷贝，Java 侧写入不会回传 JS**；
  Java 对象方法一律用 `plus.android.invoke(obj, name, args...)` 调用；
  App 端 vue3 无 `window`，plus 挂在 `globalThis.plus`
- 备用：adb push 到 `_doc/`（应用私有目录）后走手动路径

## 9. PC 工具（tools/）

| 工具 | 用途 |
|---|---|
| `make_package.bat` | 一键出包（UV4 -r 全量重建 Boot+APP → merge_image.py） |
| `merge_image.py` | 合并整片包 + 生成 OTA 发布件（自动取版本号）；**手动调用必须显式传参** |
| `flash_package.bat` | NSpyocd 整片烧录（需 NS-LINK，先关 Keil） |
| `ble_ota_update.py` / `ble_ota.bat` | **OTA 参考实现**（BLE 默认，`--uart COMx` 串口）；锁步/重发/回连复核的标准实现，新主机端照此移植 |
| `ble_cli_test.py` / `ble_cli.bat` | BLE CLI 测试客户端（帧协议 + `-rw` 读写特征两种模式） |
| `ble_temp_watch.py` | 温度监测 |

Python 环境：`tools/.venv-ble`（bleak/pyserial）；本机 `python` 可能是商店占位
stub，脚本内已处理全路径查找。

## 10. 扩展指南

### 10.1 加一条 CLI 命令

1. `mcm-ddc-ble/src/cli_core.c` 的 `s_cmds[]` 加 `{name, help, handler}`，实现 handler
   （输出经 `cli_printf`，自动同时可用 UART 与 BLE e0003）
2. 递增版本号 → 出包 → 烧录验证
3. App 侧如需业务封装，在 `McmCommands.ts` 加函数（命令名常量集中在顶部）

### 10.2 加一个信息项（温度/转速类遥测）

1. 固件 `app_info.c` 加数据源，`app_ble_proto.c` 的 TLV 组装加一项（新 id）
2. 协议文档 §5 表格登记；App `McmInfo.ts` 的 `parseTlv` 加分支 + `DeviceInfo`
   加字段（旧 App 会按 len 跳过未知 id，天然兼容）
3. 版本号 + 出包 + 修改记录

### 10.3 加一个 GATT 特征

1. 固件 `app_rdtss.c` 的 `app_rdts_att_db` 加声明+值条目（注意 `RDTSS_IDX_NB`），
   UUID 取 `...e0006` 起顺延；读写回调在 `app_ble_proto.c` 按 att_idx 分发
2. App `BluetoothManager.ts` 加 UUID 常量与读写封装；`scanServices` 校验清单
   按需更新（**注意：校验清单变严会让旧固件连不上，考虑兼容性**）
3. 手机端 GATT 缓存注意：特征表变更后若手机行为异常，系统蓝牙关开/
   忽略设备清缓存

### 10.4 加一条 OTA 传输通道

设备侧 OTA 引擎与通道解耦：新通道只需①把收到的字节流喂给帧重组器、
②注册应答 sink。参考 UART 通道（`ota` 命令模式切换）与 BLE e0005 通道
（写帧→读应答轮询）。主机端参考 `tools/ble_ota_update.py` 与
`SmartAssiter/src/mcm/McmOta.ts`。

### 10.5 加 APP_DATA 参数字段

1. `app_params.h` 的 `caiic_params_t` 加字段（保持 magic+CRC 结构；reserved
   有余量，优先占用 reserved 保持记录长度 52B 不变）
2. `appget/appset` 命令加 key；JSON 模式同步
3. App `McmCommands.ts` 的 `AppParams` 类型与解析同步

### 10.6 App 加一个页面/业务

- BLE 一律走 `BluetoothManager` 的 `MyApiResult` 回调约定；设备业务封装进
  `src/mcm/`；不改 `uni_modules` 官方组件；页面注意**缩进用 tab**
- HBuilderX 运行调试；云端接口走 `api/httpInstance.ts`（SERVER_LIST 三地址）

## 11. 验证与排障手段

1. Keil 命令行构建 0 Error/0 Warning；出包核对 map 的 `__initial_sp` 与 bin
   向量表初始 SP 一致
2. 串口 banner/`caiic->`/`devinfo` 人工确认；`blelog on` 抓 BLE 帧（走 printf
   不经 BLE，避免自激）
3. BLE 链路对照：PC `ble_cli_test.py` / `ble_ota_update.py` 与手机 App 互验
4. App 侧控制台日志体系：`[MCM]`（连接/tx/rx hex/超时/重试）、`[CLI]`、
   `[INFO]`、`[OTA]`（帧）、`[OTA-PAGE]`（选包/升级流程）、`[HOME]`
5. 变砖恢复：SWD 重烧整片包

## 12. 铁律清单（变更前必读）

1. IRAM 从 0x20004000 起；BLE init 后 VTOR 必须为 0 且不再重设
2. PA4/PA5（SWD）禁止占用；不用 cmsis_os 封装；SysTick 由 FreeRTOS port 接管
3. USART1_IRQn 优先级 3（ISR 内调 FromISR API 的硬性要求）；BLE_SW/FIFO IRQ
   优先级 0 且禁止 FromISR API
4. ke_msg/ke_timer 只允许在 BLE 调度任务上下文运行；CLI 输出经环形缓冲由
   BLE 任务发上行
5. 出包必须 UV4 -r 全量；Keil 下载只能 Erase Sectors；每改固件必升版本号
6. 帧 CRC16 覆盖 4+payLen 字节；OTA 逐帧锁步；END 应答送达后才复位
7. 安卓 BLE：初始化先 MTU 后读写；10007 重试；通道隔离；OTA 期间不开轮询
8. 固件重大改动追加 `docs/开发日志.md`；协议改动同步 `docs/ble_protocol.md`；
   App 改动写 `SmartAssiter/docs/修改记录_日期_主题.md`；同步更新 `AGENTS.md`