本文基于 CH584 MCU 的 BLE 心率传感器项目，逐层拆解 BLE 外设的配对流程。文中的代码注释和配置均来自项目实际源码。

系统架构

整个 BLE 协议栈运行在沁恒 CH58x 系列的 TMOS 任务调度系统之上。调用链路如下：

Main.c 主循环
  └─ ble_peripheral_process() → TMOS_SystemProcess()
       └─ 事件分发 ble_peripheral_process_event()
            └─ GAPRole_PeripheralStartDevice() → 启动设备
                 └─ GAP → GATT → SM（安全管理器）
                      └─ CH58x BLE Controller（硬件链路层）

Main.c 在主循环中交替执行 ble_peripheral_process() 和应用调度器。协议栈事件通过 TMOS 消息机制异步回调到应用层。

编译期 BLE 配置

项目在 src/app_project_config.h 中覆盖了 SDK 的默认 BLE 参数：

SDK 层 CONFIG.h 还控制了绑定存储的硬件参数：

配对初始化

入口函数 ble_peripheral_init() 位于 src/ble_peripheral.c:103，分三步完成初始化。

第一步：底层初始化

CH58x_BLEInit();          // BLE 协议栈库初始化
HAL_Init();               // 硬件抽象层初始化
GAPRole_PeripheralInit(); // 配置为 Peripheral 角色

CH58x_BLEInit() 内部配置 SNV 的 Flash 读写回调，为绑定数据持久化准备硬件通路。

第二步：广播与连接参数

#define BLE_PERIPHERAL_ADV_INTERVAL      160  // 160 × 0.625 ms = 100 ms
#define BLE_PERIPHERAL_MIN_CONN_INTERVAL 6    // 6 × 1.25 ms = 7.5 ms
#define BLE_PERIPHERAL_MAX_CONN_INTERVAL 6    // 同上，固定连接间隔
#define BLE_PERIPHERAL_SLAVE_LATENCY     0    // 无延迟
#define BLE_PERIPHERAL_CONN_TIMEOUT      100  // 100 × 10 ms = 1 s

广播间隔 100 ms，连接间隔固定 7.5 ms，适合低延迟数据传输。

第三步：安全参数——核心决策

uint32_t passkey  = 0u;
uint8_t  pair_mode = GAPBOND_PAIRING_MODE_WAIT_FOR_REQ;  // 等主机发起
uint8_t  mitm      = FALSE;                               // 无 MITM 保护
uint8_t  bonding   = FALSE;                               // 不保存绑定
uint8_t  io_cap    = GAPBOND_IO_CAP_NO_INPUT_NO_OUTPUT;  // 无输入输出

GAPBondMgr_SetParameter(GAPBOND_PERI_DEFAULT_PASSCODE, sizeof(passkey), &passkey);
GAPBondMgr_SetParameter(GAPBOND_PERI_PAIRING_MODE, sizeof(pair_mode), &pair_mode);
GAPBondMgr_SetParameter(GAPBOND_PERI_MITM_PROTECTION, sizeof(mitm), &mitm);
GAPBondMgr_SetParameter(GAPBOND_PERI_IO_CAPABILITIES, sizeof(io_cap), &io_cap);
GAPBondMgr_SetParameter(GAPBOND_PERI_BONDING_ENABLED, sizeof(bonding), &bonding);

Bonding 关闭意味着每次断开后不会保存对端设备的密钥信息，重连时需要重新完成配对流程。

配对方式：Just Works

当前配置组合 (NoInputNoOutput + MITM=FALSE) 决定了采用 BLE 的 Just Works 配对：

Central（手机）                        Peripheral（CH58x）
     │                                       │
     │──── Pairing Request ─────────────────→│  主机发起配对
     │←─── Pairing Response ────────────────│  IO=NoInputNoOutput, Bonding=0
     │                                       │
     │  ← 双方用 TK=0 计算确认值和 STK →    │  无用户交互
     │                                       │
     │←── Encryption Start ─────────────────→│  链路加密建立

• 临时密钥 TK 固定为 0，无用户交互
• 无 MITM 保护，链路上的中间人攻击无法被检测
• 不存储 LTK / IRK / CSRK，设备断电或断开后密钥全部丢失

广播与扫描响应

设备启动后发出两类广播数据：

广播包（31 字节上限）：

Flags: LE General Discoverable + BR/EDR Not Supported
Service UUID: 0xFFF0（自定义服务）

扫描响应（在主机主动扫描时返回）：

设备名称: "CH584F_HR_PROTO"（15 字符完整名称）
连接间隔范围: 最小 6，最大 6（固定 7.5 ms）
TX Power: 0（未显式指定功率值）

广播过滤策略使用默认值 GAP_FILTER_POLICY_ALL，未启用白名单过滤。

连接与断开事件流

应用层通过 ble_peripheral_state_changed() 回调处理状态迁移。该函数在 ble_peripheral.c:330 实现：

状态机转换：

   [空闲/广播中]
        │ GAP_LINK_ESTABLISHED_EVENT
        ▼
   [已连接]
        ├─ 记录 conn_handle
        ├─ 80 TU 后发起连接参数更新请求
        └─ 激活 TinyFrame 协议层
        │
        │ GAP_LINK_TERMINATED_EVENT
        ▼
   [等待/广播中]
        ├─ 清除连接句柄
        ├─ 清除协议层连接状态
        └─ 若之前广播已开启 → 自动恢复广播

连接参数更新请求始终使用相同的 min/max 间隔（6），本质上是在确认而非协商。断开后广播恢复逻辑由 ble_peripheral_set_advertising() 的状态变量 g_ble_peripheral_advertising_enabled 控制——如果应用层此前开启了广播，断开后自动延续。

绑定回调：当前全部为空

协议栈通过 gapBondCBs_t 结构体向应用层通知配对事件：

static gapBondCBs_t g_ble_peripheral_bond_callbacks = {
    NULL,  // passcodeCB   — 动态密码请求
    NULL,  // pairStateCB  — 配对状态变化
    NULL,  // oobCB        — OOB 安全配对
};

三个回调全部为 NULL 的影响：

• passcodeCB = NULL：使用静态 Passkey=0，无法动态生成或向用户展示密码
• pairStateCB = NULL：不感知配对进度，出现失败时无日志也无重试
• oobCB = NULL：OOB 安全配对不支持

SNV 绑定存储：硬件已就绪，尚未启用

BLE_SNV = TRUE 已在 CONFIG.h 中开启，Flash 读写回调已在 CH58x_BLEInit() 中注册。但由于 bonding = FALSE，协议栈不会实际写入任何绑定数据。

如果将来启用 bonding，每个绑定设备将占用 6 条 NV 记录，NV ID 计算公式为：

nvID = (bondIdx * 6 + offset) + 0x0200

offset 0: gapBondRec_t    — 设备地址、地址类型、状态标志
offset 1: gapBondLTK_t    — 本地 LTK（16 bytes）、ediv、rand、keySize
offset 2: gapBondLTK_t    — 对端 LTK
offset 3: IRK (16 bytes)  — 身份解析密钥
offset 4: CSRK (16 bytes) — 签名解析密钥
offset 5: SignCounter      — 签名计数器（uint32_t）

存储区域位于 Flash 末尾（0x77000 - FLASH_ROM_MAX_SIZE），单块 256 bytes。如果设备需要绑定多台主机，需要调整 BLE_SNV_NUM 扩大存储空间。

启用安全配对的方法

如果需要提升安全性，按以下顺序修改：

1. 启用 Bonding

uint8_t bonding = TRUE;
GAPBondMgr_SetParameter(GAPBOND_PERI_BONDING_ENABLED, sizeof(bonding), &bonding);

2. 实现绑定回调

至少实现 pairStateCB，在 GAPBOND_PAIRING_STATE_BOND_SAVED 状态时记录绑定完成。如果需要动态密码，则实现 passcodeCB。

3. 为 GATT 特征添加加密权限

当前 BLE UART 服务的读写权限不加加密限制（ble_uart_service_16bit.c）。需要修改两处：

RX 特征值（第 138 行），将 GATT_PERMIT_WRITE 替换为：

GATT_PERMIT_ENCRYPT_WRITE,

TX 特征 CCCD（第 124 行），将 GATT_PERMIT_READ | GATT_PERMIT_WRITE 替换为：

GATT_PERMIT_ENCRYPT_READ | GATT_PERMIT_ENCRYPT_WRITE,

加密后，主机必须先完成配对建立加密链路，才能读写这些特征。GATT_PERMIT_ENCRYPT_READ 和 GATT_PERMIT_ENCRYPT_WRITE 定义在 CH58xBLE_LIB.h 中，分别为 0x40 和 0x80。

4. 按需启用 MITM

如果设备有显示或输入能力，可以启用 MITM 保护：

uint8_t mitm = TRUE;
uint8_t io_cap = GAPBOND_IO_CAP_DISPLAY_YES_NO;

注意：启用 MITM 后配对需要用户交互（确认数字或输入密码），对无屏设备不适用。

总结

当前固件的 BLE 配对策略可以归纳为几条关键事实：

• 配对模式为 Just Works，无认证、无 MITM 保护
• Bonding 关闭，断开后不记忆设备，每次重连都需要重新配对
• SNV Flash 存储已配置但未使用
• 广播在断开后自动恢复，遵循应用层的开关状态
• 连接间隔固定 7.5 ms，延迟极低，适合心率数据实时传输
• 升级到安全配对只需修改 bonding 标志、实现回调、添加加密权限三步

FlashDB 是面向 MCU Flash 的数据管理组件，LittleFS（Little File System） 是为微控制器设计的文件系统。两者经常一起出现在 MCU 的 Flash 存储方案里。

它们解决的问题不同：

• FlashDB：面向 KV 数据和日志的数据管理层
• LittleFS：文件系统

FlashDB 与 LittleFS 通常使用不同分区并列工作：

                    应用
              +------+------+
              |             |
          FlashDB        LittleFS
          KV / TSDB      文件与目录
              |             |
             FAL        块设备接口
              |             |
          数据库分区       文件分区
              +------ Flash ------+

FlashDB 也支持 POSIX 或 C 标准库文件模式。采用文件模式时，FlashDB 经文件接口访问底层文件系统；移植层提供相应文件接口适配后，该文件系统可以是 LittleFS。两者存在并列分区和文件模式两种组合，不能固定画成唯一的上下层关系。

一、LittleFS 的底层原理

LittleFS 是为 MCU NOR Flash 设计的文件系统。

它主要解决三个问题：

1. Flash 擦写寿命有限
2. 掉电保护
3. 在有限 RAM 下管理小块更新

1. Flash 的限制

普通 Flash：

读取：

addr -> data

很简单。

但是写入：

1 -> 0

在满足芯片 program size、对齐和编程次数限制时可以直接写。

但是：

0 -> 1

必须：

擦除整个 sector

例如：

Flash:

Sector 0
+----------------+
|1111111111111111|
+----------------+

写入:

11111111 -> 11110000

OK


00001111 -> 11111111

必须 erase

erase 操作：

• 慢
• 有次数限制

具体擦除寿命由 Flash 型号和数据手册决定。存储层需要避免少量 sector 承担全部高频更新。

LittleFS 如何保存文件

LittleFS 保存一个文件时，需要记住两类内容：

• 文件说明：文件名、文件大小，以及文件内容存放在哪里。
• 文件内容：用户真正写入的数据。

很小的文件可以直接和文件说明放在一起。文件较大时，文件说明只记录内容的位置，真正的数据会放在其他数据块中。

源码把存放文件说明的成对空间称为 metadata pair，把连接大文件数据块的结构称为 CTZ skip-list。理解后面的过程只需记住：前者负责指出文件在哪里，后者负责保存较大的文件内容。

下面用单个数据块表示较大文件的一次更新。它只展示提交顺序，不代表 LittleFS 每次修改都会复制整个文件：

修改前：

文件说明中记录的位置
    |
    v
+-----------+
| block 10  |
|   AAAA    |
|  有效数据  |
+-----------+


写入新数据：

旧引用 -------------> block 10（旧数据仍然有效）

                       block 20
                     +-----------+
                     |   BBBB    |
                     |  正在写入  |
                     +-----------+


提交完成：

更新后的文件说明
    |
    v
+-----------+
| block 20  |
|   BBBB    |
|  新数据    |
+-----------+

block 10 不再被文件引用，之后可重新分配

写入期间，旧文件状态仍可读取。文件内容及相关属性会在 sync 或 close 时提交到文件系统：

写入新的数据块 → 在 metadata pair 中追加一条带 CRC 的提交，记录新的文件位置 → 旧数据块失去引用 → 以后重新使用旧空间

这种“先写新内容，再追加提交新的文件位置”的做法叫作 copy-on-write，也就是写时复制。较大文件的 CTZ skip-list 本身含有块之间的引用，但 LittleFS 不会原地改写一张统一的指针表：新数据块写好后，新的 CTZ 位置会随 metadata commit 一起追加，并由 CRC 判断提交是否完整。小文件以内联形式保存在 metadata pair 中，更新时同样通过 metadata commit 提交。它的好处是新内容确认完成前，旧内容仍然有效。即使写入失败或途中断电，系统仍能使用旧文件；只有新内容完整写入且提交有效后，文件位置才会切换过去。

2. Metadata Pair（LittleFS 核心）

成对保存的直接好处是：更新过程中始终保留一个已经写完整的版本。平时追加新内容时，旧内容仍然存在；需要擦除、整理其中一块时，另一块仍保留可用内容。即使此时断电，重新启动后也能回到最近一次完整提交。

一个 metadata pair 由两个 block 地址组成。这两个 block 不要求物理连续。每个 metadata block 自身是一段可追加的提交日志，一次提交由若干 metadata entry 和末尾的 CRC 组成。

metadata pair = {block 5, block 21}

当前活动 block：

revision | commit A + CRC | commit B + CRC | 未写空间

空间足够时，更新会直接追加到当前 metadata log，不需要在两个 block 之间来回切换。当前 block 需要压缩时，LittleFS 擦除 pair 中作为目标的另一个 block，把仍然有效的最新条目和递增后的 revision count 写进去，并用 commit CRC 完成提交。原活动 block 会保留为旧版本，等以后角色再次轮换时才被擦除。

挂载时，LittleFS 使用 revision count 比较两个 block，并通过 CRC 排除掉电时未完成的 commit。metadata pair 的掉电安全来自旧提交仍然存在、commit CRC 检错和压缩时的双 block 冗余，不能只概括成“先写 block 6，再切换指针”。

3. 均衡磨损

Flash 的每一小块空间都有擦除寿命。如果配置文件始终占用同一个位置，每次修改都让这一块承担擦除，其他位置却很少使用，这一块会最先老化。

LittleFS 使用一小段 lookahead buffer 记录当前扫描范围内哪些块可以使用。需要新空间时，它从当前范围继续向后寻找，走到 Flash 末尾后再从头开始。挂载时，LittleFS 会根据已经通过 CRC 检查的提交计算一个 seed，再用它选择扫描起点；随着有效提交发生变化，起点也可能变化，因此不会固定从 block 0 开始。

只使用固定位置：

block 10：擦除、擦除、擦除、擦除……
block 11：几乎不用
block 12：几乎不用


LittleFS 分散使用：

第一次使用 block 10
下一次使用 block 11
继续使用 block 12
走到末尾后再从前面寻找空闲位置

目录等信息如果长期占用同一块，LittleFS 也会在达到一定使用次数后把它换到其他位置。

这种做法只能分散“允许换位置”的数据。一个文件写入后长期不变，LittleFS 不会为了平衡寿命主动搬动它。因此这里的“均衡”表示尽量分散擦除次数，不表示每一块的使用次数完全相同。

4. 垃圾回收

垃圾回收要解决的问题很直接：新内容写到新位置后，Flash 中会留下旧版本。旧版本不能立刻擦除，因为新版本可能还没有写完；确认新版本完整后，旧空间才可以重新使用。

LittleFS 需要处理两类旧内容。

第一类是目录、文件名和文件位置等信息。每次修改都会在后面追加一个新版本。空间逐渐写满后，LittleFS 把仍然有效的最新内容整理到成对的另一块中：

整理前：

A旧 | B有效 | A新 | C有效 | 剩余空间很少

整理后：

A新 | B有效 | C有效 | 空闲空间

新的一块写完并确认有效后，原来那块暂时保留为旧版本，以后轮换到它时再擦除使用。这样即使整理途中掉电，旧版本仍能用于恢复。

第二类是文件内容。文件修改时，新内容写到新位置，文件记录随后改为指向新内容。旧位置失去引用，下一次寻找可用空间时就可以被识别出来：

修改前：文件记录 -> block 10

修改后：文件记录 -> block 20
                    block 10 已无文件引用

以后需要空间：擦除 block 10，再写入其他内容

LittleFS 不会把所有有效数据集中搬到一片连续区域。它主要整理写满的目录信息，并在寻找空闲空间时重新利用已经没有文件引用的块。

二、FlashDB 原理

FlashDB 提供面向 Flash 的数据库接口，不提供目录、路径和普通文件语义。它包含两种数据库：

• KVDB
• TSDB

1. KVDB

Key Value Database

例如：

wifi_ssid = "home"

motor_speed = 100

device_id = 123456

KV 不需要绑定固定物理地址：

地址:

0x1000 wifi_ssid
0x1100 motor_speed

更新后的记录会写入新的空闲位置：

Flash:

Record1:
key=wifi_ssid
value=home


Record2:
key=motor_speed
value=100


Record3:
key=wifi_ssid
value=office

KVDB 可选用 KV cache 直接定位记录。未启用缓存或缓存未命中时，find_kv 会遍历 sector 中的记录，寻找名称匹配、CRC 正确且状态为 FDB_KV_WRITE 的记录。读取逻辑不能简化成每次扫描并取“最后一条同名记录”。

2. FlashDB 的核心：追加写与单向状态机

FlashDB 会先把数据库分区切成多个 sector，再在每个 sector 中顺序存放 KV：

数据库分区

+------------+------------+------------+
| sector 0   | sector 1   | sector 2   |
+------------+------------+------------+


一个 sector 内部

+-------------+----------+----------+----------+
| sector 说明 | KV 记录1 | KV 记录2 | 空闲空间 |
+-------------+----------+----------+----------+


一条 KV 记录

+------+-------------------+------+-------+
| 状态 | 长度、校验值等说明 | key  | value |
+------+-------------------+------+-------+

sector 开头的说明记录这一块当前是否正在使用、是否含有旧数据。每条 KV 开头也有自己的状态字段，后面才是 key 和 value。因此，“单向状态机”并非一个单独的控制器，它就保存在 Flash 中每条 KV 记录的开头，设备重启后仍然可以读到。

状态变化利用 NOR Flash 可从 1 写成 0 的特点。每向前推进一个状态，只需把更多位写成 0，不用先擦除整个 sector；已经推进的状态无法原路改回，所以称为“单向”。KV 的主体数据仍采用追加写，旧记录只改变状态，新值写入后面的空闲位置。

修改一个已有 KV 时，源码中的顺序是：

旧 KV：WRITE → PRE_DELETE
新 KV：PRE_WRITE → 写入 header/name/value/CRC → WRITE
旧 KV：PRE_DELETE → DELETED

如果在更新中途掉电，初始化恢复会处理这些中间状态：CRC 正确的 PRE_DELETE 旧记录会被搬移恢复，停留在 PRE_WRITE 的未完成新记录会被标记为错误。这个状态机才是 KV 更新掉电恢复的关键。

3. 为什么不用直接改？

因为 Flash：

修改：

00001111

想变：

11111111

需要：

erase

追加新记录时：

只需要：

写新位置

4. FlashDB 的垃圾回收

比如：

Flash:

A=1
B=2
A=3
C=4
A=5

状态仍为 WRITE 的有效记录：

A=5
B=2
C=4

已经删除或写入失败的记录：

A=1
A=3

KV 更新多次以后，同一个 sector 里会混合有效记录、已删除记录和写入失败的记录。完整空 sector 所剩不多时，KVDB 开始回收：

1. 给准备回收的 sector 做标记

2. 逐条检查里面的记录

3. 把确认写完整、仍未删除的 KV 搬到其他可写位置

4. 擦除原 sector，使它重新变成空闲空间

第一步的标记用于应对掉电。如果设备在搬运途中断电，下次启动时能发现回收尚未完成，并继续执行。FlashDB 会搬走一个 sector 里的有效 KV；LittleFS 则分别整理目录信息和寻找已经没有文件使用的旧块，两者做法不同。

5. TSDB（时间序列数据库）

TSDB 用来保存不断产生、按时间排列的数据。例如传感器每隔一段时间产生一条温度记录：

time      temp

10:01     25

10:02     26

10:03     27

每条记录由两部分组成：

• 索引：记录状态、时间戳，以及实际数据的长度和位置。
• 实际数据：温度、湿度、错误信息等用户内容。

FlashDB 在一个 sector 的两端同时写入。索引从前向后增加，实际数据从后向前增加，中间是尚未使用的空间：

低地址                                                    高地址

+------------+--------+--------+----------+--------+--------+
| sector说明 | 索引1  | 索引2  | 空闲空间 | 数据2  | 数据1  |
+------------+--------+--------+----------+--------+--------+
                         →          ←
                    索引向后增长   数据向前增长

这样安排有两个好处：实际数据可以保持不同长度，不必给每条记录预留同样大的空间；索引长度固定，第 N 条索引的位置可以直接用“起始地址 + N × 索引长度”算出，也就可以在索引区使用二分查找。

追加一条记录时，FlashDB 按下面的顺序写入：

1. 在新索引中标记“正在写”
2. 写入时间戳、数据长度和数据位置
3. 把实际数据写到 sector 尾部
4. 将索引状态改成“写入完成”

最后一步相当于正式提交。设备在前三步中途断电，这条记录仍带有“正在写”标记，不会变成“写入完成”状态。重新启动后，FlashDB 能据此识别它没有完成。当前版本没有给每条时间序列记录单独保存 CRC，掉电时主要依靠这个写入顺序区分完整记录和半条记录。

TSDB 要求新记录的时间戳大于上一条记录，这为二分查找提供了前提。实际代码不会对整个数据库直接二分：它先逐个检查 sector 的起止时间，找到可能包含目标时间的 sector；随后在这个 sector 的定长索引区中二分查找起点；找到后再按固定步长顺序读取索引，直到超出查询时间范围，并根据索引中的地址读取实际数据。它支持顺序查询、倒序查询和指定时间范围查询。

一个 sector 写满后，TSDB 会继续写下一个 sector。默认开启循环覆盖：所有 sector 都用完后，擦除最旧的 sector，继续保存新数据。

sector 0 → sector 1 → sector 2 → 回到 sector 0
                                      ↓
                              擦除最旧 sector 后继续写

关闭循环覆盖后，所有 sector 写满就停止追加并返回空间不足，旧记录会一直保留。

这种结构适合：

• IoT
• 传感器
• 日志

三、FlashDB 和 LittleFS 的区别

两者分散磨损的方式不同。LittleFS 用 block_cycles 控制 metadata 达到一定使用次数后主动换块，并通过空闲块分配分散动态数据；FlashDB 不记录每个 sector 的擦除次数，KVDB 的分散效果来自垃圾回收和 sector 轮转，TSDB 则来自开启循环覆盖后的顺序复用。

四、实际 MCU 项目怎么选？

例如 ESP32：

存配置：

wifi账号
设备参数
校准值

↓

FlashDB KVDB

存升级文件：

web页面
图片
模型文件

↓

LittleFS

存运行日志：

温度历史
错误记录

↓

FlashDB TSDB

实际工程常见组合：

             APP

              |
      +-------+-------+
      |               |
   FlashDB         LittleFS
      |               |
  参数/日志        文件资源

              |
          SPI NOR Flash

五、源码阅读入口

1. LittleFS源码里的 block allocator + metadata pair
2. FlashDB源码里的 sector manager + KV cache + GC

这两组模块分别覆盖空间分配、元数据提交、记录检索和垃圾回收，是理解两套存储机制的主要入口。

本文核对的源码基线：

• FlashDB commit 8236571
• LittleFS commit 6cb4e86

六、FlashDB 和 LittleFS 如何处理数据错误

掉电中断和数据存放多年后发生位翻转，是两类不同的错误。前者发生在写入过程中，后者可能发生在一条记录或一个文件早已写完之后。

这些机制主要负责发现错误并避开不完整的数据，无法凭一份损坏的数据还原原值。需要长期冷存储时，可以在 TSDB payload 或 LittleFS 文件格式中加入 CRC；重要数据还应保存副本，检测到一份损坏后才能用另一份修复。

最近我使用 WCH 的 CH585 开发一个低功耗蓝牙项目，需要完成 ADC 采样、TFLM 异常检测和蓝牙定时传输

借助 Codex 配合 GPT-5.5，我在几天内完成了 Demo 开发

CH585 的开发接近标准库风格，没有 CubeMX 这样的图形化工具

人给出顶层架构设计后，先用 AI 完善项目的执行文档。AI 可以阅读指定路径下的官方示例、查询数据手册，再按设计补齐实现

有人说：“看起来你什么也不用干，都是机器在干，应该和你关系不大”

我的回复是：如果 AI 有一天能够独立理解目标、规划系统、验证结果、处理意外，并对最终交付负责，这个项目确实和我关系不大。目前 AI 还没有形成这样的闭环

上面提到几天完成 Demo 开发，听起来很顺利，实际执行很坎坷

AI 是概率机器。面对信息缺失、约束冲突和稀缺场景，总有概率覆盖不到的地方，它就会犯错

概率覆盖不到的地方，需要人的知识和经验

人的工作价值体现于决定目标、边界和取舍，给出顶层架构设计

同时，如果使用 AI，就必须对 AI 的结果负责

AI 提高了执行速度，也放大了工程判断的差距

用 AI 可以推进得更快，也需要人对结果负责，才能把项目做

人的思想才是灵魂所在，AI 是执行工具。

蓝牙 Mesh 与传统 BLE 的本质区别

传统 BLE 是点对点连接：手机连耳机、手环连手机，一对一，连接建立后才能通信。蓝牙 Mesh 换了一种思路：它不建立连接，直接基于广播 (flooding) 构建多对多网络。每个节点在 3 个广播信道上发送和接收消息，听到消息后如果自己是目标就处理，不是就转发（如果开启了 Relay），消息像涟漪一样扩散到整个网络。

这个设计带来了几个直接影响：

• 没有连接，没有主从。任何节点可以和任何节点通信，只要它们在同一个网络里。
• 范围可扩展。两个节点距离太远？中间节点会帮你转发。
• 天然支持组控。发一条消息到一个组播地址，订阅了该地址的所有节点同时响应。
• 代价是带宽极低。广播信道速率有限，加上 flooding 带来的消息冗余，实际可用吞吐量很低。

网络中的四种角色

蓝牙 Mesh 定义了四种可选功能角色，组合使用来适应不同场景：

约束：Friend 和 Low Power 是互斥的，一个节点不能同时充当两者。另外，Relay 功能会显著增加功耗，电池设备通常不开 Relay。

在 CH585 SDK 中，这些功能通过编译宏控制（注意 LPN/Friend 的注册要先于 Relay 初始化）：

// app.c 中的功能初始化
#if(CONFIG_BLE_MESH_FRIEND)
    friend_init_register(bt_mesh_friend_init, friend_state);
#endif
#if(CONFIG_BLE_MESH_LOW_POWER)
    lpn_init_register(bt_mesh_lpn_init, lpn_state);
#endif
// ... 中间还有 cfg_set、comp_register 等步骤 ...
#if(CONFIG_BLE_MESH_RELAY)
    bt_mesh_relay_init();
#endif

对应的 SDK 示例工程覆盖了所有角色组合：adv_vendor（基础节点）、adv_vendor_friend（Friend）、adv_vendor_low_power（LPN）、adv_proxy（Proxy）。

四大阶段：从入网到通信

一个蓝牙 Mesh 节点的完整生命周期分为四个阶段。

第一阶段：初始化

初始化的顺序是固定的，不能随意调换。以 CH585 SDK 的 blemesh_on_sync() 为例（为可读性做了精简，保留核心调用和顺序；实际使用时务必检查返回值，参考 SDK 原版 app.c 中的完整错误处理）：

void blemesh_on_sync(void)
{
    mem_info_t info;
    info.base_addr = MESH_MEM;
    info.mem_len = ARRAY_SIZE(MESH_MEM);

    // 1. Friend/LPN 功能注册（如有），位于 cfg_set 之前
#if(CONFIG_BLE_MESH_FRIEND)
    friend_init_register(bt_mesh_friend_init, friend_state);
#endif
#if(CONFIG_BLE_MESH_LOW_POWER)
    lpn_init_register(bt_mesh_lpn_init, lpn_state);
#endif

    // 2. 设置 Mesh 全局参数（内存池、Flash、RF 参数）
    GetMACAddress(MACAddr);
    tmos_memcpy(dev_uuid, MACAddr, 6);
    bt_mesh_cfg_set(&app_mesh_cfg, &app_dev, MACAddr, &info);
    hal_rf_init();

    // 3. 注册 Composition Data——告诉协议栈这个设备有什么能力
    bt_mesh_comp_register(&app_comp);

    // 4. 按需初始化各功能模块
#if(CONFIG_BLE_MESH_RELAY)
    bt_mesh_relay_init();
#endif
#if(CONFIG_BLE_MESH_PROXY || CONFIG_BLE_MESH_PB_GATT)
    // ... proxy beacon / gatts notify 等注册 ...
    bt_mesh_proxy_init();
#endif
    bt_mesh_prov_init(&app_prov);

    // 5. 初始化协议栈各层
    bt_mesh_mod_init();
    bt_mesh_net_init();
    bt_mesh_trans_init();
    bt_mesh_beacon_init();
    bt_mesh_adv_init();

    // 6. 从 Flash 恢复配网信息
#if(CONFIG_BLE_MESH_SETTINGS)
    bt_mesh_settings_init();
    settings_load();
#endif

    // 7. 判断是否已配网
    if (bt_mesh_is_provisioned()) {
        APP_DBG("Mesh network restored from flash");
    } else {
        prov_enable();  // 发送未配网 Beacon，等待 Provisioner 发现
    }
}

关键点：bt_mesh_cfg_set 中传入的 ble_mesh_cfg_t 结构体决定了整个协议栈的运行时资源，包括消息缓存数量、分段参数、Friend/LPN 队列大小等。这些参数配小了会丢消息，配大了浪费 RAM。

// app_mesh_config.c 中的资源配置
const ble_mesh_cfg_t app_mesh_cfg = {
    .common_cfg.adv_buf_count = CONFIG_MESH_ADV_BUF_COUNT_DEF,
    .net_cfg.msgcache_count = CONFIG_MESH_MSG_CACHE_DEF,  // 消息去重缓存
    .net_cfg.subnet_count = CONFIG_MESH_SUBNET_COUNT_DEF,  // 子网数量
    .net_cfg.appkey_count = CONFIG_MESH_APPKEY_COUNT_DEF,  // AppKey 数量
    .net_cfg.rxseg_count = CONFIG_MESH_RX_SEG_COUNT_DEF,   // 接收分段数
    .net_cfg.rxsdu_max = CONFIG_MESH_RX_SDU_DEF,           // 最大接收 SDU
    .friend_cfg.frndlpn_count = CONFIG_MESH_FRIEND_LPN_COUNT_DEF, // Friend 能服务几个 LPN
    // ...
};

第二阶段：配网 (Provisioning)

配网是新设备加入 Mesh 网络的唯一入口，由 Provisioner（配网器）发起。协议支持两种承载方式：

• PB-ADV：通过广播信道配网，是纯 Mesh 设备的默认方式
• PB-GATT：通过 GATT 连接配网，手机 App 配网时使用

配网流程：

未配网设备发 Beacon → Provisioner 扫描并邀请 → 建立 provisioning link
→ ECDH 交换公钥 → OOB 认证（可选：数字比对、输入密码等）
→ Provisioner 分发 NetKey + Unicast Address + IV Index
→ prov_complete 回调触发

在代码中体现为：

static const struct bt_mesh_prov app_prov = {
    .uuid = dev_uuid,          // 设备 UUID，用于被 Provisioner 识别
    .link_open = link_open,     // 链路打开回调
    .link_close = link_close,   // 链路关闭回调
    .complete = prov_complete,  // 配网完成回调——此时设备正式入网
    .reset = prov_reset,        // 节点被重置回调
};

配网完成后，设备拿到了三个关键凭证：

• NetKey：网络层加密密钥，整个子网共用
• Unicast Address：设备的唯一地址（0x0001 ~ 0x7FFF）
• IV Index：用于防重放攻击的序列号基础

第三阶段：配置 (Configuration)

配网只是拿到了"入场券"，节点还不能通信。Provisioner 需要通过 Configuration Model 进行三步配置，顺序严格不可变：

① NetKey Add     → 确认网络密钥
② AppKey Add     → 分发应用层密钥
③ Model-App Bind → 将 AppKey 绑定到具体 Model
④ Subscription Add → 给 Model 设置订阅地址（可选但实际必做）

在 app.c 的 cfg_srv_rsp_handler 中可以清楚看到这个顺序逻辑：

static void cfg_srv_rsp_handler(const cfg_srv_status_t *val)
{
    if (val->cfgHdr.status) {
        // 操作执行失败
        APP_DBG("warning opcode 0x%02x", val->cfgHdr.opcode);
        return;
    }
    if (val->cfgHdr.opcode == OP_APP_KEY_ADD) {
        APP_DBG("App Key Added");
        tmos_start_task(App_TaskID, APP_DELETE_LOCAL_NODE_EVT, APP_WAIT_ADD_APPKEY_DELAY);
    }
    else if (val->cfgHdr.opcode == OP_MOD_APP_BIND) {
        APP_DBG("Vendor Model Binded");
        tmos_start_task(App_TaskID, APP_DELETE_LOCAL_NODE_EVT, APP_WAIT_ADD_APPKEY_DELAY);
    }
    else if (val->cfgHdr.opcode == OP_MOD_SUB_ADD) {
        APP_DBG("Vendor Model Subscription Set");
        tmos_stop_task(App_TaskID, APP_DELETE_LOCAL_NODE_EVT);
    }
}

第四阶段：发布/订阅通信

配置完成后，节点通过发布 (Publish) / 订阅 (Subscribe) 模型进行通信：

• Server 模型向某个地址发布状态数据
• Client 模型****订阅该地址来接收数据
• 地址可以是单播、组播或虚拟地址

在 CH585 SDK 中发送一条消息：

static int vendor_model_srv_send(uint16_t addr, uint8_t *pData, uint16_t len)
{
    struct send_param param = {
        .app_idx = vnd_models[0].keys[0],  // 使用绑定的 AppKey 加密
        .addr = addr,                       // 目标地址（组播或单播）
        .trans_cnt = 0x01,                  // 协议层重传次数
        .period = K_MSEC(400),              // 应用层发送间隔
        .rand = (0),                        // 随机延迟
        .tid = vendor_srv_tid_get(),        // 事务 ID，用于去重
        .send_ttl = BLE_MESH_TTL_DEFAULT,   // 跳数限制
    };
    return vendor_message_srv_send_trans(&param, pData, len);
}

period 不能太小：协议规定重传间隔不应小于 200 + 50 × TTL ms。如果你的 TTL 是 7，那最小间隔就是 550ms。设太小会导致消息拥塞。

协议约束速查

这些是实际开发中最常碰到的硬限制：

7 字节的限制意味着什么？控制开关灯只需要 1 个字节，没问题。但如果想透传一段自定义数据，几乎一定会触发分段传输。分段传输涉及 Segment Acknowledgment，延迟和丢包风险都会增加。

常见开发坑点

1. 配置顺序不能乱

NetKey → AppKey → Bind → Subscription，跳步或乱序都会收到 STATUS_INVALID_APPKEY 或 STATUS_CANNOT_BIND 错误。这不是 SDK 的设计选择，是蓝牙 Mesh 协议规范强制要求的。

2. 消息发送间隔不能太小

.period = K_MSEC(400),  // 不小于 (200 + 50 * TTL) ms

如果周期太快，协议栈来不及处理重传确认，会返回 EBUSY。需要高速上报的场景，蓝牙 Mesh 不适合，考虑用 BLE 直连。

3. Friend 和 LPN 互斥

一个节点不能同时启用 Friend 和 Low Power 功能。这是协议的定义：Friend 是"帮忙的人"，LPN 是"被帮忙的人"，一个节点不能同时是两者。

4. 配网信息要持久化

配网完成后，NetKey、AppKey、Unicast Address、IV Index、Sequence Number 等都需要写入 Flash。settings_load() 在每次启动时恢复这些信息。如果存储失败或丢失，节点只能重置后重新配网。

5. 中继风暴

在一个密集网络中，如果所有节点都开启 Relay 且 TTL 设得很大，一条消息会被反复中继，造成广播风暴。实践中：

• TTL 不要超过网络直径 + 2
• 不是所有节点都需要开 Relay
• 利用 msgcache_count 配置消息缓存来过滤已处理过的消息

6. Model 回调中不要做耗时操作

Model 的消息处理回调是在协议栈的上下文中执行的，做耗时操作（如 Flash 写入、长时间计算）会阻塞协议栈处理后续消息。应该把耗时任务通过事件或队列异步处理。

总结

蓝牙 Mesh 用广播代替连接、用 flooding 代替路由，换来了多对多通信和网络自愈能力，代价是带宽和功耗。理解它的流程（初始化 → 配网 → 配置 → 发布/订阅）和约束（7 字节小包、严格配置顺序、角色互斥），是写好 Mesh 应用的前提。

CH585 的 MESH_LIB 把这些协议细节封装得很好，你主要需要关注三件事：app_mesh_config.c 里的资源配置、app.c 里的配网回调处理、以及 Model 的消息收发逻辑。对照 SDK 提供的十几个示例工程，基本可以覆盖大多数应用场景。

CH58X 系列（CH585/CH584）的 NFC-A 外设同时支持 PCD（Proximity Coupling Device，读卡器）和 PICC（Proximity Integrated Circuit Card，卡模拟）两种角色。FIFO（First In First Out，先进先出队列）是数据透传的核心——双方各维护一个发送队列，上层应用往里塞数据，通信层在每次交互时取出并发送。SDK 没有提供开箱即用的"透传模式"，但底层的 PCD（读卡器）/PICC（卡模拟）API 允许在 ISO 14443-3A 传输层之上构建任意数据交换。一块芯片做读卡器发起命令，另一块做卡响应，双方通过自定义命令码通信。

核心思路

PCD（读卡器）主动发起通信，PICC（卡模拟）被动响应。ISO 14443-3A 的标准选择流程——REQA（Request，寻卡指令）→ ANTICOLL（Anti-Collision，防冲突）→ SELECT（选中）——完成后，PICC（卡模拟）进入 ACTIVE 状态。在此状态下，data_handler 回调可以识别自定义命令码，读写任意数据缓冲区。每次数据交换由 PCD（读卡器）发起一帧，PICC（卡模拟）回复一帧。

两端如何收发数据

PCD（读卡器）端——主动发、等回复：

PCD（读卡器）是通信的发起方。先把要发送的数据填入 g_nfca_pcd_send_buf，调用 nfca_pcd_communicate(data_bits_num, recv_mode, offset)——前两个参数指定要发送的比特数和接收模式，第三个参数 offset 是首比特在首字节中的偏移（0-7），通常填 0。芯片会自动把数据调制成 13.56 MHz 射频信号发射出去，发完后自动切换到接收模式，等待 PICC（卡模拟）回复。轮询 nfca_pcd_get_communicate_status 直到状态变为 DONE，回复数据就从 g_nfca_pcd_recv_buf 里读，长度用 nfca_pcd_get_recv_data_len 获取。

整个过程是：填发送缓冲 → 调 communicate → 等状态结束 → 读接收缓冲。

PICC（卡模拟）端——被动收、填回复：

PICC（卡模拟）靠读卡器的射频场供电，不能主动发数据。SDK 通过回调机制处理通信：注册一个 nfca_picc_cb_t 结构体，其中 data_handler 是核心回调，在中断里被调用。每当读卡器发来一帧数据，g_picc_data_buf 里就是收到的内容，bits_num 是比特数。你在这个回调里解析命令、准备响应：把回复数据写入同一个 g_picc_data_buf，校验位写入 g_picc_parity_buf，最后返回回复的比特数，芯片自动完成后续的射频回复。

整个过程是：data_handler 被触发 → 读 g_picc_data_buf → 写回复到同一缓冲 → 返回比特数。

通信流程

1. PCD（读卡器）发 REQA（寻卡，0x26）/WUPA（唤醒，0x52）→ PICC（卡模拟）回 ATQA（寻卡应答）→ PICC（卡模拟）进入 READY 状态
2. PCD（读卡器）执行 ANTICOLL（防冲突，0x93）+ SELECT（选中）→ PICC（卡模拟）回 UID（唯一标识符）+ SAK（选中确认）→ PICC（卡模拟）进入 ACTIVE 状态
3. ACTIVE 状态下，PCD（读卡器）可发送任意自定义命令码，PICC（卡模拟）的 data_handler 处理并回复

PICC（卡模拟）端可以参考 SDK 中 T2T（Type 2 Tag，NFC Forum 定义的标签标准之一）示例（wch_nfca_picc_t2t.c）的 NFCA_PICC_T2T_STATE_ACTIVE 分支，把 READ/WRITE 等标准命令替换为自己的协议即可。

FIFO 交换帧格式

PCD（读卡器）必须持续轮询才能维持通信，每次轮询本身就是一次数据交换机会。一个实用的做法是双方各维护一个发送 FIFO，每次帧交互时顺带捎上自己的 FIFO 数据：

PCD → PICC 帧：

PICC → PCD 响应帧（不含命令码，其余结构相同）：

序号和确认的设计：

• 一字节掰两半：高 4 位是自己的序号（0-15 循环），低 4 位是对上一帧的确认。NFC 单帧数据量有限，每字节都要省着用，合并到一个字节里零额外开销。
• 捎带确认：第一帧的确认在第二帧里完成。发送方每发出一帧，同时告诉对方"你上一帧我收到了"。如果序号连续递增且超时没收到 ACK，发送方就知道上一帧丢了。
• PICC（卡模拟）响应帧不需要命令码——PICC（卡模拟）是被动方，收到 PCD（读卡器）命令后回复，双方都知道当前处于哪一轮交互。

关键点：

• 没有数据也要轮询。长度字段填 0，仍然发完整帧，序号照常递增、ACK 照常捎带。通道始终保持活跃，上层随时可以塞数据进来。
• 每一轮都是双向的。PCD（读卡器）发一帧带走自己的 FIFO 数据，PICC（卡模拟）回复时顺带捎上自己的 FIFO 数据。一轮轮询完成一次双向交换。
• PCD（读卡器）侧在主循环里反复调用 nfca_pcd_communicate（每次调用会阻塞直到通信完成或超时），PICC（卡模拟）侧在 data_handler 里识别 0xF0 命令码，读出对方数据、填入自己的 FIFO 数据、返回响应。

断连与恢复

PICC（卡模拟）离开射频场后，PCD（读卡器）的 nfca_pcd_communicate 会超时返回错误。PCD（读卡器）侧需要在主循环中检测这个状态：超时后停止对当前卡的轮询，回到 REQA 重新寻卡。

PICC（卡模拟）侧离场后回调 offline 被触发，状态回到 IDLE。重新进入射频场时回调 online 被触发，之后必须重新走完整的选卡流程（REQA → ANTICOLL → SELECT）才能再次进入 ACTIVE 状态接收数据帧。

这意味着上层协议要能接受通信中断：数据 FIFO 在断连期间可能积压，恢复后需从断点继续，而不应假设通道永远在线。

传输中途断开的数据保护

断连最棘手的情况发生在发送中途——已经从 FIFO 取出了数据，但 NFC 发送失败，数据不能丢，又不能塞回 FIFO。用暂存区解决：

1. 从内部 FIFO 取出一定量数据，放到一个暂存区（staging buffer）
2. 用暂存区里的数据组帧，尝试 NFC 发送
3. 发送成功 → 暂存区清空，下次从 FIFO 取新数据
4. 发送失败（超时/断连）→ 暂存区数据保留，下次轮询时直接用暂存区里的数据重试，无需动 FIFO

这样数据流向是单向的：FIFO → 暂存区 → NFC 发送。数据从 FIFO 取出后只往前走，失败就停在暂存区里等下次重试，不需要回退。

至于链路层的丢包或 CRC 校验失败，不在这一层处理——保持通信层轻量，数据完整性校验和重传策略交给上层应用决定。

限制

• PICC（卡模拟）只能响应，无法主动发起传输，双向通信必须由 PCD（读卡器）端轮询
• 单帧大小受 SDK 默认缓冲限制——PCD（读卡器）发送缓冲默认 32 字节（NFCA_PCD_DATA_BUF_SIZE），PICC（卡模拟）数据缓冲默认 20 字节（PICC_DATA_BUF_LEN）。如需更大帧可自行增大这些宏，但需确保 RAM 足够
• 速率固定 106 kbps（ISO 14443A 标准），不支持更高波特率
• PICC（卡模拟）的 data_handler 在中断中运行，不可长时间阻塞；ATQA 回复必须在约 90 μs 内发出

先说结论：沁恒官方不推荐在 CH58x 系列上同时使用 RTOS 和 BLE。 BLE 协议栈是闭源库，深度绑定 TMOS 调度系统，无法剥离。RT-Thread 移植 readme 第 8 条明确写了「不建议使用蓝牙」，EVT 包里也找不到任何一个 RTOS + BLE 的例程。低功耗模式更是彻底不兼容（官方论坛明确回应「FreeRTOS + BLE low power consumption cannot coexist」）。

本文记录的是社区摸索出来的 workaround——在 RT-Thread 里创建一个低优先级任务循环调用 TMOS_SystemProcess()，配合一系列补丁让两个调度器勉强共存。技术上社区有成功的移植案例（如 MX-WCH-RTOS-SDK），但这不是官方支持的使用方式，生产环境需自行评估风险。

坑一：SysTick 被 BLE 初始化覆盖

现象：BLE 初始化完成后，RT-Thread 的 rt_tick 不再增长，系统调度停止；或者反过来，BLE 连接立即断开。

原因：RT-Thread 启动时会配置 SysTick 作为系统心跳，通常 1ms 一次中断。CH58X_BLEInit() 内部同样会调用 __SysTick_Config(SysTick_LOAD_RELOAD_Msk) 配置 SysTick，虽然紧接着就关了 SysTick 中断（PFIC_DisableIRQ(SysTick_IRQn)），但 SysTick 的配置寄存器已经被覆盖。TMOS 的时间基准来自 RTC（SYSTEM_TIME_MICROSEN 625us），不依赖 SysTick——但 BLE 初始化覆盖 SysTick 配置这个副作用仍然会让 RT-Thread 的系统心跳失效。

解决：在 CH58X_BLEInit() 内部找到 __SysTick_Config() 调用并注释掉，只保留 RT-Thread 的 SysTick 配置。BLE 初始化完成后，RT-Thread 需要重新配置一次 SysTick 以确保心跳参数正确。

// 在 CH58X_BLEInit() 内部：
// SysTick_Config(...);   // ← 注释掉，交给 RT-Thread 管理

坑二：LLE 中断内部做环境切换，RT-Thread 任务调度破坏上下文

现象：蓝牙广播和连接都正常，运行几秒到几分钟后系统死机或数据错乱，无固定规律。

原因：CH585 的蓝牙链路层中断 LLE_IRQHandler 在中断处理过程中，协议栈会在中断内部保存当前上下文，切换到另一个运行环境等待 BLE 硬件事件完成。如果这个过程中 SysTick 中断恰好触发了一次 RT-Thread 任务调度，调度器会尝试保存"当前任务"的上下文，但此时 CPU 正处于 BLE 协议栈的另一个运行环境中，上下文被错误保存，导致数据损坏甚至死机。

解决：在 ble_task_scheduler.S 的 LLE_IRQHandler 入口加临界区保护，退出时恢复。

/* ↓ 示意代码，基于 EVT ble_task_scheduler.S 原始代码修改 ↓ */
LLE_IRQHandler:
    addi    sp, sp, -32*4            /* 分配 32 个寄存器保存空间 */

    sw      x1,  1 * 4(sp)           /* 保存 ra  */
    sw      x4,  2 * 4(sp)           /* 保存 tp  */
    sw      x5,  3 * 4(sp)
    /* ... x6~x30 按偏移依次保存 ... */
    sw      x31, 29 * 4(sp)

    /* ★ 关键：停掉 RT-Thread 调度，防止在 BLE 内部环境切换时切入 */
    call    rt_hw_interrupt_disable

    la      a1, g_LLE_IRQLibHandlerLocation
    lw      a0, 0(a1)
    jalr    x1, 0(a0)                /* 通过函数指针间接调用 BLE 库处理函数 */

    /* ★ 关键：恢复 RT-Thread 调度 */
    call    rt_hw_interrupt_enable

    lw      x1,  1 * 4(sp)
    lw      x4,  2 * 4(sp)
    /* ... x6~x30 按偏移依次恢复 ... */
    lw      x31, 29 * 4(sp)

    addi    sp, sp, 32*4
    mret

以上为示意代码，基于 EVT BLE/LIB/ble_task_scheduler.S 的原始代码修改，插入的 rt_hw_interrupt_disable / rt_hw_interrupt_enable 来自 RT-Thread 移植 readme 第 12 条的明确要求。实际修改时务必以你的 EVT 版本中的原始汇编为准。

坑三：TMOS 事件执行太久，BLE 连接超时

现象：在 GATT 写回调或 TMOS 定时事件中加了 Flash 写入、外设等待等操作后，BLE 连接不规则断开。

原因：TMOS 是单线程事件循环，所有 BLE 事件都在同一个循环中依次处理。BLE 对时序极其敏感，每个连接间隔内主从设备必须按约定时间窗口交换数据。如果某个 TMOS 事件回调执行了 20ms 的 Flash 擦写，连接间隔只有 30ms，对端设备连续几次收不到响应就会判定超时断开。

解决：单次 TMOS 事件执行时间控制在连接间隔的一半以内。耗时操作拆分成多个小事件，通过事件链逐步执行。

// ❌ 错误：在 GATT 回调中直接做耗时操作
void gatt_write_callback(uint8_t *data, uint16_t len)
{
    flash_erase_page(0x1000);        // 耗时 20ms+
    flash_write(0x1000, data, len);  // 直接阻塞 TMOS 循环
}

// ✅ 正确：只做数据缓存，通过事件链异步处理
void gatt_write_callback(uint8_t *data, uint16_t len)
{
    memcpy(g_rx_buffer, data, len);
    tmos_set_event(task_id, EVENT_FLASH_WRITE);  // 延迟到下一个 TMOS 周期
}

void flash_write_event_handler(void)
{
    flash_write_page(g_current_page++, g_rx_buffer + offset, 256);
    if (!finished) {
        tmos_set_event(task_id, EVENT_FLASH_WRITE);  // 继续下一批
    }
}

坑四：在中断里直接调用 BLE 函数

现象：在 GPIO 中断或定时器中断中调用 GATT_Notification() 等 BLE 发送函数，系统死机或数据发不出去。

原因：TMOS 不可重入，BLE 函数内部依赖 TMOS 事件机制，必须运行在任务上下文中。

解决：中断只置标志，在 RT-Thread 任务或 TMOS 事件回调中执行 BLE 操作。

// GPIO 中断
void GPIO_IRQHandler(void)
{
    if (GPIO_ReadITFlagPort() & GPIO_Pin_5) {
        g_send_flag = 1;                           // 只置标志
        rt_sem_release_from_isr(g_ble_sem);         // 通知任务
        GPIO_ClearITFlagBit(GPIO_Pin_5);
    }
}

// RT-Thread 任务
void ble_send_task(void *param)
{
    while (1) {
        rt_sem_take(g_ble_sem, RT_WAITING_FOREVER);
        if (g_send_flag) {
            g_send_flag = 0;

            attHandleValueNoti_t noti;
            noti.handle = g_char_handle;
            noti.len = len;
            tmos_memcpy(noti.value, data, len);
            GATT_Notification(conn_handle, &noti, FALSE);
        }
    }
}

坑五：任务优先级排错

现象：BLE 数据卡顿，或 TMOS 任务长期得不到执行。

推荐配置：

RT-Thread Nano 中 IDLE 任务优先级通常为 31（最低）。TMOS 任务设置为优先级 23，业务任务设置为 46——即 TMOS 低于业务、远高于 IDLE。"仅比 IDLE 高一级"这个说法容易让人误解为设置为 30，实际上 readme 的意思是 TMOS 任务处于低优先级区间、不抢占业务即可。

这里容易有一个误解：TMOS 本身会主动让出 CPU（TMOS_SystemProcess() 处理完事件队列就返回，没有事件时几乎立即返回），并不会永久占据 CPU。优先级不建议过高的真正原因是 BLE 的硬实时保障在 LLE 中断层——连接间隔的严格时序由硬件中断保证，不依赖 TMOS 任务的优先级。TMOS 任务只负责消化中断产生的事件（GATT 回调、连接参数更新、广播刷新等），这些事件只要在下一个连接间隔到来之前处理完即可。因此 TMOS 任务可以设为低优先级，让传感器采集、电机控制等对延迟敏感的业务任务优先拿到 CPU，业务跑完后再由 TMOS 在空闲时间里收尾 BLE 事件。

rt_thread_t tmos_thread = rt_thread_create(
    "tmos",
    tmos_task_entry,
    RT_NULL,
    1024,    // 栈大小，建议 ≥ 1024 字节
    3,       // 优先级，低于用户业务任务
    5        // 时间片
);

坑六：自定义连接参数太紧凑

现象：RT-Thread 任务频繁被 BLE 中断打断，业务逻辑执行效率低。

EVT 官方 Peripheral 例程的默认连接参数本身已经比较宽松（MAX 间隔 125ms）。但很多开发者会为了低延迟把连接间隔改小，在 RTOS 场景下这会进一步挤压业务任务的 CPU 时间。

解决：如果需要自定义连接参数，保持宽松的配置。

// EVT Peripheral 默认值（参考 peripheral.c）
#define DEFAULT_DESIRED_MIN_CONN_INTERVAL    6     // 7.5ms
#define DEFAULT_DESIRED_MAX_CONN_INTERVAL    100   // 125ms（本身已较宽松）
#define DEFAULT_DESIRED_SLAVE_LATENCY        0
#define DEFAULT_DESIRED_CONN_TIMEOUT         100   // 1s

// RTOS 场景建议值（如果默认值仍不够宽松）
#define DEFAULT_DESIRED_MIN_CONN_INTERVAL    12    // 15ms
#define DEFAULT_DESIRED_MAX_CONN_INTERVAL    100   // 125ms
#define DEFAULT_DESIRED_SLAVE_LATENCY        4     // 可跳过 4 个间隔
#define DEFAULT_DESIRED_CONN_TIMEOUT         500   // 5s 超时

关键调整是增大 SLAVE_LATENCY（允许从机跳过若干连接间隔），在 MAX 间隔 125ms + 4 次延迟的最长窗口下，RT-Thread 有约 625ms 完整时间片执行业务任务。不要随意减小 MAX_CONN_INTERVAL——越小 BLE 中断越频繁，留给 RT-Thread 的时间越少。

整体架构

RT-Thread 调度器
│
├── 传感器采集任务（优先级 4）
├── 数据处理任务（优先级 5）
├── TMOS 循环任务（优先级 2，仅比 IDLE 高一级）
│     └── while(1) { TMOS_SystemProcess(); }
│           └── TMOS 内部：GATT 回调、连接管理、广播刷新
├── IDLE 任务
│
└── 中断层
      ├── LLE_IRQHandler（+ rt_hw_interrupt_disable/enable）
      └── SysTick_IRQ（RT-Thread 心跳）

调试顺序

1. 裸机验证：关掉 RT-Thread，确认裸机 BLE 例程正常工作
2. 单独验证：关掉 BLE，确认 RT-Thread 多任务调度正常
3. 合入检查：在 SysTick 中断和 TMOS 处理中各加一个 GPIO 翻转，用逻辑分析仪观察时序
4. 栈检查：用 list_thread 检查 TMOS 任务栈使用量，确保没有溢出
5. 临界区验证：在 LLE_IRQHandler 的 rt_hw_interrupt_disable/enable 前后加 GPIO 翻转，确认保护区间覆盖了 BLE 库函数调用

其他 CH585 特有约束

以下来自 RT-Thread 移植 readme，除第 8、11、12 条外，也是在使用 BLE 时必须注意的：

• 关闭全局中断再初始化 BLE（readme 第 8 条）：初始化蓝牙时需要先关闭全局中断，等初始化完成后再开启。蓝牙使用免表中断，StartUP.S 已将 BB_IRQLibHandler 和 LLE_IRQLibHandler 放入中断向量表
• 禁止裸开关中断（readme 第 12 条）：不可使用 __enable_irq() / __disable_irq()，必须使用 RT-Thread 的 rt_hw_interrupt_disable() / rt_hw_interrupt_enable()
• mscratch 寄存器（readme 第 7 条）：已被中断系统占用，用户代码不可使用
• 中断函数修饰（readme 第 4 条）：统一入口中断（unified_interrupt_entry）不需要 __attribute__((interrupt(...))) 修饰；非统一入口中断需要
• 统一入口中断无需手动调 enter/leave（readme 第 10 条）：unified_interrupt_entry 中已调用 rt_interrupt_enter 和 rt_interrupt_leave，用户中断函数内不要重复调用
• 中断栈（readme 第 5 条）：所有统一入口中断会切换到独立中断栈（_eusrstack），务必在 LD 脚本中预留足够 RAM，否则中断中栈溢出直接 HardFault
• 中断函数放高速 RAM（readme 第 2 条）：外部中断函数建议用 __attribute__((section(".highcode"))) 修饰
• BLE_LibInit 调用顺序：TMOS_SystemProcess() 必须在 CH58x_BLEInit()（内部调用 BLE_LibInit()）成功之后才能调用，否则会访问未初始化的库内部数据结构

参考资料

• MX-WCH-RTOS-SDK — 社区维护的 CH585/CH582 RT-Thread Nano + BLE 移植参考
• WCH 论坛：RT-Thread 上使用 BLE 的一些疑惑
• WCH 论坛：rtt 工程加了蓝牙后，断连
• WCH 论坛：CH585M FreeRTOS tickless BLE
• CH585 EVT EXAM/FreeRTOS/readme.txt — 官方 FreeRTOS 移植说明（RT-Thread 同理可参考）

CH585 上 RT-Thread + BLE 的核心做法：TMOS 作为 BLE 的微调度器跑在 RT-Thread 的低优先级任务里，LLE 中断中以临界区保护阻止 RT-Thread 在 BLE 内部环境切换时切入，TMOS 事件执行时间控制在连接间隔的一半以内。

再次强调：这是社区摸索出来的 workaround，不是官方推荐方案。 低功耗模式完全不可用——BLE 需要 TMOS 运行，RTOS 的 tickless 低功耗与 TMOS 的 RTC 时间基准直接冲突，官方已明确回应无法共存。如果你的产品需要 BLE + 低功耗，纯 TMOS 是唯一选择。只有在确实需要 RTOS 的多任务能力、可以放弃低功耗、并且愿意承担踩坑成本时，才考虑本文的方案。

关于代码示例：文中的汇编和 C 代码为示意代码，基于 EVT 原始文件修改，未经过编译验证。实际移植时务必以你的 SDK 版本中的实际代码为准。

SOP8 只有 8 个引脚。VCC 和 VSS 吃掉两个，剩下 6 个。如果你需要两路通信接口、两路传感器输入、一路控制输出，6 个引脚刚好用完。然后你发现 PA13（SWDIO）、PA14（SWCLK）和 PF2（NRST）全都被迫让位给了业务功能。接着你烧不进去程序了。

这篇文章梳理 SOP8 封装的 SWD 引脚复用策略、恢复机制和防砖实践，不涉及具体产品设计，只讲通用方法。

SOP8 的引脚布局

PY32F002AL15S（SOP8）的引脚分配：

     VCC  1    8  VSS
PA4/PA10  2    7  PA1
     PA3  3    6  PA2/PF2-NRST
PA14-SWC  4    5  PA13-SWD
    /PB3

注意三个共享焊盘：

• Pin 2：PA4 和 PA10 二选一（通过 SYSCFG 寄存器选择）
• Pin 4：PA14（SWCLK）和 PB3 二选一
• Pin 6：PA2 和 PF2-NRST 二选一（PF2/NRST 通过 Option Bytes 切换）

每个被占用的调试引脚意味着什么：

三者全占 = 常规 SWD 调试通路全部切断。

SWD 引脚的生存窗口

ARM Cortex-M0+ 上电后，PA13 和 PA14 的默认状态是 AF0（SWDIO + SWCLK）。这个状态一直保持到用户固件执行 GPIO 初始化把它们切走。

上电 -> SystemInit -> main -> GPIO_Init(PA13, ...) -> SWD 消失
                              ^
                     窗口在这里关闭，微秒级

在 24MHz 的 PY32F002A 上，从复位释放到 GPIO 初始化执行完，通常不到 1 毫秒。除非你主动把窗口拉大，否则调试器不够时间连上来。

三层防线

第一层：启动延迟

在 main() 开头加一段 delay，再切 SWD 引脚。Milton 在他的 PY32 博文里推荐 2 秒：

int main(void)
{
    HAL_Init();
    SystemClock_Config();

#ifdef DEBUG_BUILD
    HAL_Delay(2000);  /* 调试版本给调试器 2 秒连接窗口 */
#endif

    /* 下面的 GPIO 初始化会重映射 PA13/PA14 */
    Remap_SWD_Pins_To_GPIO();

    /* ... 业务逻辑 ... */
}

用 #ifdef DEBUG_BUILD 包住，量产时一关宏就去掉了。

这层防线的漏洞： 如果固件在 delay 之前就 crash 了（时钟配置写错、HardFault），窗口直接消失。这只是买时间，不是真正的恢复机制。

第二层：Connect Under Reset

这是真正的防线。原理如下：

NRST = LOW  -> Core 处于复位状态 -> SWD 引脚 = AF0（默认）
            -> 调试器通过 SWD 连接成功
            -> 调试器在 Reset Handler 入口设硬件断点
NRST = HIGH -> Core 释放复位 -> 立即停在断点 -> 用户代码还没跑

调试器在芯片还处于复位状态时就接管了 SWD 总线，然后在第一条用户指令之前设下断点。用户代码连 main 都没进去。

前提是 NRST 引脚必须可用。几种调试器的操作方式：

如果 J-Link 连不上，先检查 NRST 线接了没有。这是最常见的漏接。

第三层：Option Bytes 与 SOP8 的限制

PY32F002A 内建了一个系统内存 bootloader，通过 USART1 烧录。拉高 BOOT0（PF4）上电就能进入。

但 SOP8 封装没有引出 PF4/BOOT0 引脚。 这条路在 SOP8 上不存在。这也是 SOP8 的终极风险：如果 SWD 死了、NRST 也没了、BOOT0 又不存在，芯片就失去了所有外部恢复手段。

20 引脚及以上的封装（TSSOP20、QFN20）有 BOOT0，可以通过 USART ISP 救砖。选 SOP8 就意味着你必须靠前两层防线保护自己。

开发用大封装，量产切 SOP8

PY32F002A、PY32F003、PY32F030 共用同一套 HAL 驱动和同一个硅片。TSSOP20 封装引出了全部 18 个 IO，SWD、NRST、BOOT0 一个不缺。开发阶段用 TSSOP20，量产阶段切 SOP8，是 PY32 系列的标准玩法。

封装的切换只是表象，真正的约束是外设子集要对齐。你在 TSSOP20 上开发时，不能用 F003 多出来的 DMA、TIM3、USART2。这些在 F002A 上根本没有。只要你只使用 F002A 也有的外设子集，从 TSSOP20 切到 SOP8 就只是改 Makefile 里 MCU_TYPE 和 linker script 的事。

引脚分配上的过渡策略：

1. TSSOP20 开发阶段： 把将来要挪到 PA13/PA14/PF2 的功能，先挂在 TSSOP20 多出来的空闲引脚上。比如最终要占用 PA13 做 GPIO 输出，开发阶段先用 PA8 代替，等切 SOP8 时再把代码里的 PA8 改成 PA13。
2. SOP8 移植阶段： 硬件换成 SOP8，功能引脚挪到目标位置。此时固件保留启动 delay 和安全模式，NRST 保持为复位引脚。验证所有外设功能正常。
3. 量产锁死： 最后一步才烧录关闭 NRST 的 Option Bytes。这一步不可逆（SOP8 没有 BOOT0 救不了），所以排在所有验证通过之后。

整个过程里，SWD 调试能力只在最后一步之前始终可用。开发调试用 TSSOP20 全功能 SWD，移植验证用安全模式保底，量产烧录一次性关闭 NRST。

启动延迟不能带到量产固件里，但可以在切 SWD 之前加一个条件判断：某个 GPIO 被外部拉低时，跳过 SWD 重映射，保持调试通道畅通。

选择检测引脚的原则：

• 正常运行时空闲为高电平（或被外部上拉）
• 外部拉低不会触发总线协议误判
• 最好是已有引脚，不额外占用

static int should_enter_safe_mode(void)
{
    /*
     * 选择某个正常运行时为高电平的引脚做安全模式检测。
     * 例如 I2C SCL 空闲时为高，外部拉低不会触发 Start 信号
     * （因为 Start 条件是 SCL 高电平期间 SDA 下降沿）。
     */
    GPIO_InitTypeDef gpio = {0};
    /* 重要：必须先使能 GPIO 端口时钟，否则 HAL_GPIO_Init 寄存器写入可能无效 */
    __HAL_RCC_SAFE_MODE_PORT_CLK_ENABLE();
    gpio.Pin = SAFE_MODE_PIN;      /* 由项目配置决定 */
    gpio.Mode = GPIO_MODE_INPUT;
    gpio.Pull = GPIO_PULLUP;
    HAL_GPIO_Init(SAFE_MODE_PORT, &gpio);
    HAL_Delay(1);
    return (HAL_GPIO_ReadPin(SAFE_MODE_PORT, SAFE_MODE_PIN) == GPIO_PIN_RESET);
}

int main(void)
{
    HAL_Init();
    SystemClock_Config();

    if (!should_enter_safe_mode()) {
        /* 正常启动：重映射 SWD 引脚到业务功能 */
        Remap_SWD_Pins_To_GPIO();
    }
    /* 安全模式下 SWD 引脚保持 AF0，调试器可正常连接 */

    /* 恢复安全模式检测引脚的业务功能（如 I2C AF） */
    Restore_SafeModePin_AF();

    /* ... 业务逻辑 ... */
}

需要更新固件时，把检测引脚临时短接到 GND 再上电就行。

为什么选 I2C SCL 类型的引脚做检测： SCL 空闲时为高电平，外部拉低不会被从机误判，因为 I2C 的 Start 条件要求 SCL 高电平期间 SDA 出现下降沿。单拉低 SCL 不会触发任何 I2C 行为。类似的，SPI 的 SCK（CPOL=0 时空闲为低，CPOL=1 时空闲为高）也可以根据实际配置选择。

NRST 什么时候可以放开

PF2-NRST 通过 Option Bytes 控制。Option Bytes 的地址是 0x1FFF 0E80，bit 14 控制 NRST_MODE：

把 PF2 改成 GPIO 的代码：

static void APP_FlashSetOptionBytes(void)
{
    FLASH_OBProgramInitTypeDef OBInitCfg;
    LL_FLASH_Unlock();
    LL_FLASH_OB_Unlock();

    OBInitCfg.OptionType = OPTIONBYTE_USER;
    OBInitCfg.USERType = OB_USER_BOR_EN | OB_USER_BOR_LEV |
                         OB_USER_IWDG_SW | OB_USER_WWDG_SW |
                         OB_USER_NRST_MODE | OB_USER_nBOOT1;
    OBInitCfg.USERConfig = OB_BOR_DISABLE | OB_BOR_LEVEL_3p1_3p2 |
                           OB_IWDG_SW | OB_WWDG_SW |
                           OB_RESET_MODE_GPIO |   /* PF2 变 GPIO */
                           OB_BOOT1_SYSTEM;

    LL_FLASH_OBProgram(&OBInitCfg);
    LL_FLASH_Lock();
    LL_FLASH_OB_Lock();
    LL_FLASH_OB_Launch();  /* 触发软复位，OB 生效。此调用不返回 */
}

关键防护： 调用前检查 OB 是否已经被改过，避免无限复位：

if (READ_BIT(FLASH->OPTR, FLASH_OPTR_NRST_MODE) == OB_RESET_MODE_RESET) {
    APP_FlashSetOptionBytes();  /* 只执行一次 */
}

NRST 改 GPIO 的时机： 放在上一节三步流程的最后一步。SOP8 硬件全部验证通过，量产烧录时才执行。在此之前 NRST 始终保持为复位引脚。

总结

SOP8 封装下占用 PA13/PA14/PF2 可以做，但要有纪律：

1. 开发时不动 SWD 和 NRST。 用引脚更多的封装调试，引脚管够。
2. 量产固件留安全模式。 一个 GPIO 拉低就让 SWD 保持打开，永远有一条路回去。
3. NRST 是最后一道防线。 没了 NRST 就等于放弃了 Connect Under Reset，最可靠的 SWD 恢复手段。把它留到最后再关。
4. SOP8 没有 BOOT0，ISP 救不了你。 防线全在前两层，软件上必须做足。

补充说明：PA10 和 PA4 在 SOP8 的 Pin 2 上是二选一关系。如果你要用硬件 I2C1，注意 PA4 不支持 I2C SDA 复用（只有 SPI1_NSS、USART1_CK），必须选 PA10（AF6 = I2C1_SDA）。类似的，Pin 4 在 PA14 和 PB3 之间二选一，如果你的外设需要独立于 SWCLK 的引脚，选 PB3（AF1 = TIM1_CH2）。选引脚前对照数据手册的复用功能映射表，避免选了不支持的组合。

选一个通信库之前，通常想知道它到底占多少 Flash 和 RAM。文档里写的"轻量级"不解决实际问题——3KB RAM 的芯片上能不能跑，CRC16 查找表有多大，缓冲区参数调到多少合适，这些需要实际编译一次才知道。

这次用 IOsetting/py32f0-template 模板，把 TinyFrame 加到 PY32F002A 工程里，用 ARM GCC 编译，测出静态增量。Demo 实现了三个 UART 查询-响应指令：PING、STATUS 和 ECHO。

测试方法

在空白模板上先编译一次作为基线，再加入 TinyFrame 编译第二次，差值就是库本身的静态开销。

环境：

• 模板：IOsetting/py32f0-template
• 芯片：PY32F002A（Cortex-M0+, 20KB Flash, 3KB RAM）
• 编译器：arm-none-eabi-gcc 13.2.1，-Os -ffunction-sections -fdata-sections -Wl,--gc-sections
• HAL 库：PY32F0xx HAL Driver（UART + GPIO + printf）
• TinyFrame：MightyPork/TinyFrame

基线工程只做 LED 闪烁 + UART printf。加入 TinyFrame 后，Demo 在 UART 上接收 TinyFrame 帧，按 TYPE 字段分发到三个监听器并返回响应。两次编译除了 TinyFrame 相关代码外，HAL 和 BSP 部分完全一致。

TinyFrame 配置

这份配置是针对 3KB RAM 裁剪过的，也是本次测量的实际参数：

Demo 注册了三个 Type 监听器和一个 Generic 监听器，初始化时调用 TF_InitStatic() 静态分配。UART 接收字节通过 TF_Accept() 喂入解析器，TF_WriteImpl() 用 HAL_UART_Transmit() 阻塞发送。

测量结果

两次编译的 arm-none-eabi-size 对比：

Flash 多出约 2.8KB，RAM 多出 360B。对于 20KB/3KB 的 PY32F002A，加上 HAL 基线后总共用掉 63% Flash 和 60% RAM，还有空间给业务逻辑。

增量拆解

从 linker map 里把 TinyFrame 相关的符号挑出来：

最大的单块 Flash 开销是 CRC16 的 512 字节查找表——占 TinyFrame 增量的 18%。RAM 开销的大头是 tf 实例本身，其中 RX 缓冲区和 TX 缓冲区合计 192 字节。

可调开关

如果 Flash 或 RAM 更紧张，可以从这几个方向压：

校验类型。 CRC16 → CRC8 省掉 500B Flash（512B 查找表换成 256B），换 XOR 或 None 再省约 20B。代价是检错能力下降，在 UART 等本身有一定误码率的链路上不建议关掉。

缓冲区大小。 TF_MAX_PAYLOAD_RX 从 128 降到 64，直接省 64B RAM。TF_SENDBUF_LEN 从 64 降到 32，再省 32B。这两个参数要和实际业务帧大小匹配——如果最大指令 payload 只有 20 字节，128 的缓冲区就是浪费。

监听器槽位。 TF_MAX_TYPE_LST、TF_MAX_ID_LST、TF_MAX_GEN_LST 每个槽位在 tf 实例中占十几个字节（指针 + 标志位）。按实际需要的最大并发监听数设置，多余的槽位是纯浪费。

字段宽度。 TF_LEN_BYTES 从 2 降到 1（如果 payload 不超过 255 字节），省少量 Flash 和几个字节 RAM。TF_ID_BYTES 同理。

去掉 SOF。 TF_USE_SOF_BYTE 设为 0，省掉帧首字节检查和相关的几行代码。在本身有帧边界机制的链路上（如 BLE Notify 每次一个完整包），SOF 可以省略。

压缩到极限后的估算（CRC8 + RX 64 + TX 32 + 最简监听器）：

结论

TinyFrame 在 Cortex-M0+ 上的静态增量约 2.8KB Flash + 360B RAM（CRC16 配置），压到极限约 2.1KB Flash + 264B RAM（CRC8 配置）。对于 20KB/3KB 的 PY32F002A 这种级别的芯片，加上 HAL 后还剩约 7KB Flash 和 1.1KB RAM 给业务层，完全够用。

这个测量方法的要点是：在真实 MCU 工程里编译，拿基线差分，不看 .o 文件大小或文档里的估算。选了芯片和工具链之后跑一次，数字比任何"轻量级"的描述都可靠。

基于 ESP-IDF v6.0.1 的 ESP32-S3 基础设施模板，提供 WiFi 配网、LittleFS、SD 卡、OTA 升级等开箱即用的功能，适合作为新项目的起点。

GitHub 仓库

功能一览

界面预览

架构

项目采用 平台 + 业务 分层架构：

• main/web_platform.c — 基础设施胶水层，负责 WiFi / OTA / 配网 / 仪表盘编排
• main/hello_web.c — 业务端点模板，从这里开始写自定义 HTTP handler
• components/ — 可复用组件（wifi_manager、ota_manager、file_manager、led_task、sd_card、sd_logger）

新项目只需在 hello_web.c 中仿照模板添加 handler，基础设施已全部就绪。

快速开始

# 克隆模板
git clone https://github.com/createskyblue/esp32s3_idf_template.git my_project
cd my_project

# 编译烧录
idf.py set-target esp32s3
idf.py build
idf.py -p COMx flash monitor

首次上电：手机搜到热点 ESP32S3-Template（密码 template1234），连接后浏览器打开任意网址自动弹出配网页面。

使用定时器测量外部信号的脉宽是嵌入式开发中的常见需求。以下场景都会遇到：

• 超声波测距，需要测量 Echo 引脚的高电平宽度
• 红外遥控解码，需要区分引导码、数据 0 和数据 1 的脉冲长度
• PPM 信号解析，多路 PWM 的上升沿间隔编码了通道值
• 旋转编码器速度测量，两个脉冲之间的时间间隔对应转速

这篇文章整理三种基于定时器捕获通道的脉宽测量方法，并讨论一个问题：硬件能自动过滤不合格的脉宽吗？哪些必须在软件里做？

PY32F002A 的定时器资源

先看一眼手里的硬件。PY32F002A（TSSOP-20 封装）有 2 个定时器：

只有 TIM1 能做输入捕获。 不过它有 4 个通道，每个通道是完全独立的硬件：独立的 CCR 寄存器、独立的输入滤波器（ICxF）、独立的预分频器（ICxPSC）、独立的中断标志。唯一共享的是一颗 16 位计数器 CNT。

硬件滤波：能做的和不能做的

每个捕获通道都有一个 4 位数字滤波器（ICxF）和一个 2 位事件预分频器（ICxPSC），在信号进入边沿检测之前工作。

数字滤波器去毛刺

滤波器用 fDTS（死区时间采样时钟，等于 CK_INT 或其 2/4 分频）对输入信号连续采样 N 次。只有 N 次采样结果一致，信号电平才被传递到边沿检测电路。

宽度小于上述值的毛刺会被硬件自动吞掉，不会触发捕获。这是纯硬件行为，你的 ISR 根本感知不到这些毛刺。

事件预分频器跳脉冲

ICxPSC 让捕获通道每 N 个边沿才响应一次：

预分频器适合周期性信号——比如你只关心每第 4 次上升沿的时间戳，中间 3 次直接忽略。

硬件不能做的：阈值判定

ICxF 滤毛刺，ICxPSC 跳脉冲。但没有寄存器可以设"脉宽小于 100 个 tick 就自动丢弃"。脉冲是否合格，必须在 ISR 里用软件判断。

好在这不难：中断里读到 CCR 值，跟前一次捕获值做差，大于最小阈值、小于最大阈值就算合格，不满足的直接丢弃。

三种捕获触发模式

每个捕获通道可以独立选择边沿触发方式：

触发条件满足时，硬件自动把当前 CNT 值锁存到对应的 CCR 寄存器里，置中断标志。整个过程不需要软件参与——你在 ISR 里读 CCR 拿到的就是边沿到达那一刻的计数器快照。

下面三种方法本质上是在这三种触发模式上做组合。

方法一：单通道双边沿 + 读引脚判方向

一个通道配成双边沿捕获，上升沿和下降沿都会触发中断。中断里读对应 GPIO 的输入电平：高说明刚才是上升沿，低说明刚才是下降沿。

// 配置：CH1 双边沿捕获 + 硬件滤波
TIM_IC_InitTypeDef sIC = {0};
sIC.ICPolarity  = TIM_ICPOLARITY_BOTHEDGE;   // 双边沿都触发
sIC.ICSelection = TIM_ICSELECTION_DIRECTTI;   // 直接连 TI1
sIC.ICPrescaler = TIM_ICPSC_DIV1;             // 每个边沿都捕获
sIC.ICFilter    = 0x0F;                       // 最强硬件滤波
HAL_TIM_IC_ConfigChannel(&htim1, &sIC, TIM_CHANNEL_1);
HAL_TIM_IC_Start_IT(&htim1, TIM_CHANNEL_1);

// ISR
void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim)
{
    static uint32_t last = 0;

    if (htim->Channel == HAL_TIM_ACTIVE_CHANNEL_1) {
        uint32_t now = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
        uint32_t diff = (now >= last) ? (now - last) : (0xFFFF - last + now);

        if (HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_8) == GPIO_PIN_SET) {
            // 引脚高 → 刚才上升沿 → diff = 低电平宽度
            if (diff > MIN_TICKS && diff < MAX_TICKS) {
                g_pulse_ticks = diff;   // 合格
            }
            // 不合格的静默丢弃
        }
        // 下降沿只记录时间戳，不计算宽度
        last = now;
    }
}

时序：

信号 ──┐        ┌──────────┐        ┌──────
       └────────┘          └────────┘
        ↓        ↑          ↓        ↑
    下降沿     上升沿      下降沿    上升沿
    CCR=100   CCR=400    CCR=650  CCR=900
    PIN=0     PIN=1      PIN=0    PIN=1
    只记录    低脉宽      只记录    低脉宽
              =400-100             =900-650
              =300                =250

优点：一个通道搞定一路信号。TIM1 有 4 个通道，够测 4 路。

代价：ISR 里要读一次 GPIO 来判断方向。对于高频脉冲，GPIO 读操作有 1~2 个 APB 周期的延迟，但绝大多数应用场景完全够用。

方法二：PWM 输入模式——两个通道绑一个信号

PWM 输入模式用两个捕获通道（CH1+CH2 或 CH3+CH4）绑到同一个输入引脚。CH1 只抓上升沿，CH2 只抓下降沿，两个通道各自独立触发，互不干扰。ISR 里不需要读 GPIO——哪个通道触发，就知道是哪个边沿。

同一个信号物理上只接一根引脚。CH2 通过 CCMR 的 INDIRECT 模式"内部布线"连到同一路 TI1 输入。

// CH1: 上升沿, 直接连 TI1
TIM_IC_InitTypeDef sIC1 = {0};
sIC1.ICPolarity  = TIM_ICPOLARITY_RISING;
sIC1.ICSelection = TIM_ICSELECTION_DIRECTTI;
sIC1.ICPrescaler = TIM_ICPSC_DIV1;
sIC1.ICFilter    = 0x0F;
HAL_TIM_IC_ConfigChannel(&htim1, &sIC1, TIM_CHANNEL_1);

// CH2: 下降沿, 间接连到同一个 TI1（不需要额外引脚）
TIM_IC_InitTypeDef sIC2 = {0};
sIC2.ICPolarity  = TIM_ICPOLARITY_FALLING;
sIC2.ICSelection = TIM_ICSELECTION_INDIRECTTI;  // 内部连 TI1
sIC2.ICPrescaler = TIM_ICPSC_DIV1;
sIC2.ICFilter    = 0x0F;
HAL_TIM_IC_ConfigChannel(&htim1, &sIC2, TIM_CHANNEL_2);

HAL_TIM_IC_Start_IT(&htim1, TIM_CHANNEL_1);
HAL_TIM_IC_Start_IT(&htim1, TIM_CHANNEL_2);

// ISR
void HAL_TIM_IC_CaptureCallback(TIM_HandleTypeDef *htim)
{
    if (htim->Channel == HAL_TIM_ACTIVE_CHANNEL_1) {
        // CH1 中断 → 一定是上升沿 → 读 CCR1（周期值）
        uint32_t period = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_1);
        g_period_ticks = period;
    }
    if (htim->Channel == HAL_TIM_ACTIVE_CHANNEL_2) {
        // CH2 中断 → 一定是下降沿 → 读 CCR2（高电平宽度）
        uint32_t high = HAL_TIM_ReadCapturedValue(htim, TIM_CHANNEL_2);
        g_high_ticks = high;
        g_low_ticks = g_period_ticks - high;   // 低脉宽 = 周期 - 高脉宽
    }
}

优点：ISR 不需要读 GPIO，不需要记上次值，边沿方向由通道号本身保证。代码干净。

代价：一路信号吃掉两个捕获通道。TIM1 最多测两路（CH1+CH2 一路，CH3+CH4 一路）。CH3+CH4 在 CCMR2 中没有 INDIRECT 模式——CH4 不能间接映射到 TI3，第二路只能退回方法一。

方法三：纯 GPIO 双边沿中断

前两种方法都需要占用定时器捕获通道。如果引脚不满足 TIM1 通道映射、或者捕获通道已挪作他用，可以用 GPIO 双边沿中断加软件状态机来测脉宽。

PY32F002A 的 EXTI 原生支持双边沿触发：

GPIO_InitStruct.Mode = GPIO_MODE_IT_RISING_FALLING;

配置之后，上升沿和下降沿都会进同一个 EXTI 中断，不需要像 51 单片机那样在 ISR 里来回切换触发边沿。ISR 里读一次引脚电平即可判断方向，再用一个自由运行的定时器（比如 SysTick 或只做时基的 TIM16）拿时间戳：

// 两路信号各用一个小的状态机
typedef struct {
    uint32_t last_tick;
    uint8_t  state;       // 0=等下降沿, 1=等上升沿
    uint32_t low_width;
} pulse_detect_t;

pulse_detect_t g_ch1, g_ch2;

void EXTI_IRQHandler(void)
{
    uint32_t now = TIM16->CNT;  // 自由运行的时间基准

    if (__HAL_GPIO_EXTI_GET_IT(GPIO_PIN_2) != RESET) {
        if (HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_2) == GPIO_PIN_SET) {
            // 上升沿 → 低电平结束
            uint32_t diff = (now >= g_ch1.last_tick) ? (now - g_ch1.last_tick)
                                                     : (0xFFFF - g_ch1.last_tick + now);
            if (diff > MIN_TICKS && diff < MAX_TICKS) {
                g_ch1.low_width = diff;  // 合格
            }
        } else {
            // 下降沿 → 低电平开始，只记录起点
            g_ch1.last_tick = now;
        }
        __HAL_GPIO_EXTI_CLEAR_IT(GPIO_PIN_2);
    }
    // 通道2 同理...
}

精度能接受吗

软件中断的延迟不是随机乱跳——Cortex-M0+ 的中断响应是确定性的 12~16 个周期。跑 48MHz 时约 0.3μs。真正引入抖动的是被其他中断或临界区短暂挡住。

以 250μs 最小脉宽为例：

中断延迟：~0.3μs
SysTick 挡住（典型）：~2μs
最坏情况 jitter：~2μs
相对误差：2 / 250 = 0.8%

对于电机霍尔、红外遥控、超声波测距这类场景完全够用。但如果脉宽是几十微秒级别，或者系统里有长时间关中断的代码（Flash 擦写、I2C 阻塞等待），误差就会明显增大。

延伸阅读：在 51 单片机上用中断捕获 12 路微秒级脉宽，软件双边沿会碰到实时性边界 的情况不同——51 主频低、路数多、脉宽窄，软件方案才会成为瓶颈。

三种方法对比

软件阈值判定的最终形态

不论用方法一还是方法二，硬件只能去毛刺，不能判断脉宽是否合法。ISR 里代码形态是相同的：

// 拿到 diff（两次捕获的 tick 差值）
if (diff < MIN_VALID_TICKS)  return;  // 太窄，丢弃
if (diff > MAX_VALID_TICKS)  return;  // 太宽，丢弃
g_valid_count++;                        // 合格
// 然后该干啥干啥

MIN 和 MAX 的取值取决于你的信号协议。红外遥控 NEC 协议逻辑 0 是 560μs，逻辑 1 是 1690μs；超声波测距 HC-SR04 高电平约 150μs~25ms。把这些物理时间换算成定时器 tick 数作为阈值，不合规的直接 return 丢弃。

延伸阅读：一种基于脉宽判定的电机霍尔反馈抗干扰方法 在电机霍尔信号上实际应用了脉宽阈值校验——用定时器捕获霍尔边沿，通过脉宽范围过滤干扰脉冲。

小结

定时器捕获通道自带两级硬件预处理：数字滤波器去毛刺，预分频器跳脉冲。这两项是纯硬件行为，不需要软件参与。

但"判定脉宽范围"必须软件做——没有硬件阈值比较器。

怎么选：

• 引脚能映射到 TIM1 CHx → 优先用方法一或方法二，硬件时间戳精度最高
• 引脚不满足 TIM1 映射、但脉宽 ≥ 100μs → 方法三的软件中断完全可用，误差在 1~2% 以内。STM32 系 EXTI 原生支持双边沿，不需要像 51 那样来回切换触发模式
• 脉宽几十微秒且关中断频繁 → 硬件定时器捕获是底线

具体到 PY32F002A：只有 TIM1 能做捕获，TSSOP-20 能引出的 TIM1 通道取决于封装。查数据手册的引脚复用表确认 CH1~CH4 对应的 GPIO 即可。TIM1 通道不够用时，TIM16 配成自由运行计数器给方法三当时间基准。

Windows 的“关闭显示器”和“系统睡眠”是两条不同路径。一次死机重启后，机器可以正常手动睡眠，但把显示器自动关闭时间设成 1 分钟后，屏幕会在熄灭后很快亮起。这个现象容易被误判成电源计划失效，实际排查入口应该先落到空闲输入计时。

现象

故障表现很窄：

• 手动睡眠可以进入低功耗状态，按电源键可以正常恢复。
• 把显示器自动关闭时间设为 1 分钟后，屏幕会按时熄灭，又很快重新亮起。
• 机器没有表现出整机睡眠后被异常唤醒的特征。

这组现象说明，问题不一定在“睡眠唤醒”。显示器熄灭只需要满足用户空闲条件；只要 Windows 认为有新的鼠标、键盘、触控板或虚拟 HID 输入，显示器就会重新点亮。

先排除电源唤醒路径

第一步先看系统有没有明确的电源阻塞或唤醒来源。几个结果比较关键：

• powercfg /requests 没有显示器、系统、执行、Away Mode 等保持唤醒请求。
• powercfg /waketimers 没有活动唤醒计时器。
• powercfg /devicequery wake_armed 没有列出允许唤醒系统的设备。
• 电源事件记录里，手动睡眠后的恢复来源是电源按钮。

这些证据把问题范围收窄到显示器空闲路径。系统并没有被某个计划任务或设备从睡眠里唤醒，屏幕重新亮起更可能来自用户输入状态被刷新。

用空闲计时验证假输入

随后直接监控 Windows 的最后输入时间。正常情况下，如果没有碰鼠标、键盘和触控板，空闲秒数应该持续递增。实际观察到的情况是，空闲秒数接近显示器关闭阈值时会突然归零。

这个结果很关键。它说明系统收到了某种输入事件，或者某个驱动/服务让 Windows 认为用户刚刚操作过。于是显示器刚进入关闭状态，又立刻被“新输入”点亮。

这里的重点是先确定判断对象：从“电源计划坏了”切换到“谁在重置空闲输入计时”。排查方向一变，后续证据就容易对齐。

可疑对象集中在虚拟输入和虚拟显示

设备和进程列表里出现了几类强相关对象：

• 远控或串流类服务。
• 模拟器相关远程服务。
• 虚拟显示适配器。
• 虚拟 HID 鼠标、键盘和供应商定义设备。

这类组件为了远程控制、投屏、模拟触控或保持会话，常会安装虚拟输入设备和虚拟显示设备。它们不一定会阻止系统睡眠，也不一定出现在 powercfg /requests 里，但仍可能刷新用户输入状态。

本次机器上最终通过停用相关虚拟输入/显示服务解决。停用后重新测试 1 分钟自动熄屏，屏幕不再马上亮起。

修复边界

这次修复采用的是隔离式处理：

• 只停用确认相关的虚拟输入/显示服务。
• 不修改电源计划的核心参数。
• 不禁用物理鼠标、键盘、触摸板和显卡。
• 不卸载驱动，先保留回滚空间。

如果还需要使用远控、串流或模拟器功能，可以逐个恢复服务并重新测试。哪个服务恢复后让空闲计时再次归零，哪个服务就是后续处理对象。后续处理可以选择更新软件、关闭它的远程输入能力、禁用虚拟显示组件，或保留服务但只在需要时手动启动。

排查经验

这类问题要把“睡眠”和“熄屏”分开看。手动睡眠正常，只能说明 S3 睡眠链路和电源按钮恢复链路可用；它不能证明显示器空闲计时没有被重置。

比较稳的排查顺序是：

1. 先看 powercfg /requests、唤醒定时器和唤醒设备，排除明确的电源阻塞。
2. 再看事件日志，确认实际唤醒来源是否指向电源按钮、设备或计划任务。
3. 如果电源路径没有异常，监控最后输入时间。
4. 如果空闲时间无人操作时归零，优先检查虚拟 HID、远控、串流、模拟器、手写板、蓝牙键盘和触摸板服务。
5. 只做可逆隔离，每次停一组相关服务，测试通过后再决定长期策略。

这次真正有用的分界点，是确认“屏幕自动亮起”来自空闲输入被刷新。只要这个判断成立，后续就应该停止反复调整电源计划，转向输入设备、虚拟驱动和后台服务。

声明： STM32 AI Model Zoo 是 STMicroelectronics 维护的开源项目。本文是阅读该项目源码、文档和模型清单后整理的学习笔记，用于理解边缘 AI 在微控制器上的工程落地方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有模型数据均来自项目文档与 manifest，不代表本文作者的设计决策。

边缘 AI 跑到了 MCU 上。Cortex-M4、Cortex-M7、Cortex-M85 —— 几十 MHz 主频、几百 KB SRAM —— 这些单片机现在能直接运行量化后的神经网络。

STMicroelectronics 开源的 stm32ai-modelzoo 是观察这个趋势的绝佳窗口。仓库收录了 14 个应用领域、43 个预训练模型，全部经过 INT8 量化，提供 TensorFlow Lite 和 ONNX QDQ 两种格式，可以直接部署到 STM32H7、STM32MP2、STM32N6 等目标平台。配套仓库 stm32ai-modelzoo-services 包含完整的训练脚本和模型架构源码。

一、视觉类（8 类）

视觉是边缘 AI 最密集的方向，从简单分类到像素级理解，Model Zoo 提供了完整的任务链。

图像分类

最基础的 CV 任务：输入一张图，输出类别标签。Model Zoo 提供了 29 个模型变体 —— 是数量最多的分类。TensorFlow 侧有 MobileNetV1/V2、EfficientNetV2、ResNet8/20/32 等经典架构；PyTorch 侧覆盖 20 种轻量网络，包括 ShuffleNetV2、RegNet、HarDNet、PeleeNet，以及 ST 自研的 ST-ResNet 系列（pico / nano / micro / milli / tiny 五个尺寸）。

预训练数据集覆盖 ImageNet、Food101、CIFAR-10/100、TF Flowers、Plant Leaf Diseases 等。输入分辨率从 128×128 到 384×384 不等。

目标检测

框出物体位置并分类。16 个模型变体，YOLO 家族是主力：Tiny-YOLOv2、YOLOv8-n、YOLOv11-n、最新的 YOLO26-n，以及 ST 自研的 ST-YOLO-LC、ST-YOLO-X 系列。SSD/SSDLite + MobileNet 组合也在列。

人脸检测

YuNet 和 BlazeFace Front 两个模型，输入分辨率 128×128 和 320×320。输出人脸框和关键点（眼睛、鼻子、嘴角），通常作为人脸识别 pipeline 的第一级。

姿态估计

检测人体 17 个关键点。包含 MoveNet（ST 改进版）、YOLOv8-n Pose、YOLOv11-n Pose，以及手部关键点和头部关键点专用模型。

语义分割

给每个像素打类别标签。基于 DeepLabV3 + MobileNetV2 backbone，256×256 和 320×320 两种分辨率。在 NPU 加速的 STM32N6 上可以实时运行。

实例分割

比语义分割更进一步 —— 区分同一类别的不同实例。YOLOv8-n Seg 和 YOLOv11-n Seg 两个模型，需要 NPU 加速。

深度估计

从单张 2D 图像推断每个像素的距离。FastDepth 模型，基于 NYU Depth v2 数据集训练。

神经风格迁移

把照片转换成指定艺术风格。Xinet-Picasso-Muse 模型，输入 160×160，在 COCO 上训练。Model Zoo 里最"好玩"的模型，也可用于相机实时滤镜和 AR 特效。

二、音频类（2 类）

音频事件检测

识别声音中的特定事件：玻璃破碎、婴儿哭声、警报声等。MiniResNetV1/V2 和 YAMNet（多种嵌入尺寸），输入是梅尔频谱图。

语音增强

从嘈杂环境中提取干净人声。STFT-TCNN 模型，在 Valentini 数据集上训练。输入带噪语音的 STFT 频谱，输出降噪后的语音。

三、传感类（4 类）

视觉和音频之外，Model Zoo 还覆盖了基于传感器信号的四个场景。

人体活动识别

通过加速度计数据判断行走、跑步、静坐等状态。ST-GMP 和 ST-IGN 两个模型，输入 48×3 的时序数据（48 个时间步、3 轴加速度）。模型极小，Cortex-M4 可跑。

手势识别

用 ToF 测距传感器（VL53L5CX / VL53L8CX）识别 8 种手势。ST-CNN2D HandPosture 模型。ToF 只拿到低分辨率深度图，天然隐私友好，适合公共场所。

电弧故障检测

检测电路中的电弧 —— 电气火灾的主要成因之一。ST-Conv（时域 CNN）和 ST-Dense（频域全连接）两个模型，输入电流采样序列。

人员重识别

判断两张照片中是否为同一个人。MobileNetV2 和 OSNet 两个模型，256×128 输入分辨率。多摄像头跟踪系统的关键组件。

四、模型架构完全开源

模型架构定义代码在 stm32ai-modelzoo-services 中完整开源。以图像分类为例：

image_classification/
├── tf/src/models/
│   ├── mobilenetv1.py        # MobileNetV1
│   ├── mobilenetv2.py        # 倒置残差 + 线性瓶颈
│   ├── efficientnetv2.py     # EfficientNetV2 B0~S
│   ├── resnet.py             # ResNet8/20/32
│   ├── squeezenetv11.py      # Fire 模块
│   └── ...
├── pt/src/models/
│   ├── mobilenetv1/          # PyTorch 版
│   ├── mobilenetv3/
│   ├── edgevit/              # EdgeViT
│   ├── stresnet/             # ST 自研 ResNet 系列
│   └── ...

每个 .py 文件是完整的模型类定义，可以逐行阅读、修改宽度因子、换激活函数、加注意力模块。通过 stm32ai_main.py 加 YAML 配置文件驱动全流程：训练 → 评估 → 量化 → 部署。

主仓库提供的是量化后的推理文件：TFLite INT8（全整数量化）和 ONNX QDQ（支持混合精度 w4/w8/a8）。

五、为什么在 MCU 上跑 AI

云端 GPU 算力远超 MCU，但在以下四个维度上本地推理有不可替代的优势：

一个典型场景：智能门铃的人形检测。如果每帧图像上传云端，延迟高、云服务持续计费、有隐私顾虑。在 STM32 上本地跑一个 300KB 的 SSD-MobileNet 模型，50ms 出结果，功耗不到 100mW。

六、总结

STM32 AI Model Zoo 覆盖了边缘 AI 的主流应用方向。从 43 个预训练模型出发，配合 modelzoo-services 的训练工具链，可以做到：选模型 → 改模型（微调或从头训练）→ 量化导出 → 上板运行。

如果你在做需要本地智能的嵌入式产品 —— 无论是产线视觉质检、智能门铃、可穿戴运动追踪，还是工业电弧检测 —— 这个仓库是一个务实的技术起点。

相关链接：

• stm32ai-modelzoo（预训练模型）
• stm32ai-modelzoo-services（训练脚本 + 模型架构源码）

本文基于 STM32 AI Model Zoo v4.1（2026 年 4 月发布）撰写。

把本文链接丢给 AI 代理即可复现全部步骤。 全文唯一需要人类操作的地方：打开一个 GitHub 网页，点击 Create codespace。其余全部由 AI 代理通过 gh 命令自动完成。

想象一下：一个几块钱的 MCU，不需要网络、不需要 Linux、不需要 MPU，就能本地运行神经网络——关键词唤醒、手势识别、振动异常检测、传感器数据拟合。设备端推理意味着零延迟、离线可用、数据不出设备、功耗低到可以用电池跑几年。

这就是 TensorFlow Lite Micro（TFLM）要做的事——目标是在只有几十 KB RAM、几百 KB Flash 的芯片上跑 AI 推理。

WCH CH585M 是一颗只要几块钱的 RISC-V 芯片——448KB Flash、128KB RAM，带 BLE。如果能在它上面跑 TFLM，就意味着一大批低成本 RISC-V 设备都有了边缘 AI 的可能性。

这篇文章记录把 TFLite Micro 真正烧进 CH585M 的过程：用 MRS IDE 编译，串口输出推理结果，最终在真实硬件上跑通 sin 函数拟合 demo。

本文用的 sin 模型是用 TensorFlow 训练的一个三层 MLP（1→10→5→1），输入 x 输出 sin(x)。模型的训练过程见《ESP32-S3 上使用 ESP-NN 加速 TFLite Micro sin 推理》。完整工程代码在 GitHub。

硬件与工具链

第一步：获取 TFLite Micro 源码

TFLM 自带官方脚本 create_tflm_tree.py，自动生成所需的完整目录树。已在 GitHub Codespace 上实测通过。

人类操作（唯一需要你动手的地方）

打开 tensorflow/tflite-micro，点击 Code → Codespaces → Create codespace on main。等 Codespace 启动（约 1-2 分钟），然后把会话交给 AI 代理。如果你使用的 AI 代理能控制浏览器，这一步 AI 可以代劳。

AI 代理操作

# 列出当前 Codespace
gh codespace list

# SSH 进去运行官方脚本
gh codespace ssh -c <codespace-name> -- "\
  pip install Pillow && \
  python3 tensorflow/lite/micro/tools/project_generation/create_tflm_tree.py /tmp/tflm-output && \
  find /tmp/tflm-output -name '*.cc' | wc -l"
# 输出应为 202

# 拉取生成的文件到工程目录
gh codespace cp remote:/tmp/tflm-output/tensorflow . -c <codespace-name>
gh codespace cp remote:/tmp/tflm-output/third_party . -c <codespace-name>

脚本生成的文件（忽略 signal/，它是信号处理库，与推理无关）：

工程目录/
├── tensorflow/     # TFLM 核心源码（202 个 .cc + 271 个 .h）
└── third_party/    # flatbuffers, gemmlowp, ruy（纯头文件）

如果本机有 Linux/WSL，直接 clone 仓库后跑 python3 create_tflm_tree.py /tmp/tflm-output 即可，不需要 Codespace。

第二步：集成到工程

拿到 tensorflow/ 和 third_party/ 后，需要做 4 件事。

删除冲突文件（9 个）

脚本生成的默认平台实现与我们要自己写的冲突：

tensorflow/lite/micro/debug_log.cc       ← 与 tflite_port/debug_log.cc 冲突
tensorflow/lite/micro/micro_time.cc      ← 与 tflite_port/micro_time.cc 冲突
tensorflow/lite/micro/system_setup.cc    ← 与 tflite_port/system_setup.cc 冲突
tensorflow/lite/micro/test_helpers.cc    ← 测试辅助，不需要
tensorflow/lite/micro/test_helper_custom_ops.cc
tensorflow/lite/micro/fake_micro_context.cc
tensorflow/lite/micro/mock_micro_graph.cc
tensorflow/lite/micro/recording_micro_allocator.cc
tensorflow/lite/micro/hexdump.cc

新增 include 路径（2 个）

脚本生成的 third_party 目录结构比手动复制多了一层：

新增编译宏（4 个）

newlib-nano 缺少部分 C++ 标准数学函数：

TF_LITE_STATIC_MEMORY               # 禁用动态内存
TF_LITE_USE_GLOBAL_CMATH_FUNCTIONS  # 缺少 std::round / std::expm1
TF_LITE_USE_GLOBAL_MAX              # 缺少 std::fmax
TF_LITE_USE_GLOBAL_MIN              # 缺少 std::fmin

Makefile 用通配符自动发现文件

不再手动列举文件名，用 $(wildcard ...) 自动匹配：

TFLM_SRCS := $(filter-out \
    %/debug_log.cc %/micro_time.cc %/system_setup.cc \
    %/test_helpers.cc %/test_helper_custom_ops.cc \
    %/fake_micro_context.cc %/mock_micro_graph.cc \
    %/recording_micro_allocator.cc %/hexdump.cc, \
    $(wildcard tensorflow/lite/micro/*.cc \
               tensorflow/lite/micro/arena_allocator/*.cc \
               tensorflow/lite/micro/memory_planner/*.cc \
               tensorflow/lite/micro/kernels/*.cc \
               tensorflow/lite/micro/tflite_bridge/*.cc \
               tensorflow/lite/core/api/*.cc \
               tensorflow/lite/core/c/*.cc \
               tensorflow/lite/kernels/*.cc \
               tensorflow/lite/kernels/internal/*.cc \
               tensorflow/lite/kernels/internal/reference/*.cc \
               tensorflow/compiler/mlir/lite/core/api/*.cc \
               tensorflow/compiler/mlir/lite/schema/*.cc))

不用担心文件太多——链接器 --gc-sections 会自动丢弃未使用的代码段。编译了全部 120+ 个算子内核后，最终固件 text 段只有 72KB。

第三步：写三个平台抽象函数

TFLite Micro 把平台相关部分收敛到三个函数。这是移植中唯一需要手写的 C++ 代码。

DebugLog

// tflite_port/debug_log.cc
#include "tensorflow/lite/micro/debug_log.h"
#include <cstdio>

extern "C" void DebugLog(const char* format, va_list args) {
  vfprintf(stderr, format, args);
}

extern "C" int DebugVsnprintf(char* buffer, size_t buf_size,
                               const char* format, va_list vlist) {
  return vsnprintf(buffer, buf_size, format, vlist);
}

TFLM 所有日志走 DebugLog()。printf 已被 CH58x HAL 层重定向到 UART（_write() 在 CH58x_sys.c 中实现）。

InitializeTarget

// tflite_port/system_setup.cc
#include "tensorflow/lite/micro/system_setup.h"

namespace tflite {
void InitializeTarget() {
  // 时钟和 UART 已在 main() 中初始化
}
}

GetCurrentTimeTicks

// tflite_port/micro_time.cc
#include "tensorflow/lite/micro/micro_time.h"

extern "C" { extern uint32_t SystemCoreClock; }

namespace tflite {
uint32_t ticks_per_second() {
  return (SystemCoreClock / 1000) ? (SystemCoreClock / 1000) : 1;
}
uint32_t GetCurrentTimeTicks() {
  volatile uint32_t dummy = 0;
  return dummy;
}
}

不用引用 CH58x_common.h，用 extern "C" 声明 SystemCoreClock 即可，避免引入不必要 HAL 依赖。

第四步：用 MRS IDE 创建工程

1. 打开 MRS IDE，创建一个 CH585M 空白工程
2. 告诉 AI 代理工程路径
3. AI 代理将 tensorflow/、third_party/、tflite_port/、src/main.cc、model_data.h 放入工程

MRS IDE 使用 Eclipse CDT 的 .cproject 管理编译选项。AI 代理需在 IDE 中配置以下项（或直接编辑 .cproject 文件）：

C++ 编译选项

预处理器宏

DEBUG=0 决定 printf 走哪个串口。CH58x_sys.c 中的 _write() 用 #if DEBUG == Debug_UART0 选择 UART0（PA14/PA15），这是板子上唯一引出的串口。

include 路径

${workspace_loc:/${ProjName}}
${workspace_loc:/${ProjName}/StdPeriphDriver/inc}
${workspace_loc:/${ProjName}/RVMSIS}
${workspace_loc:/${ProjName}/third_party}
${workspace_loc:/${ProjName}/third_party/gemmlowp}
${workspace_loc:/${ProjName}/third_party/flatbuffers/include}
${workspace_loc:/${ProjName}/third_party/ruy}

链接器

• 链接库：-lISP585 -lstdc++
• 链接脚本：Ld/Link.ld
• 关键：C 和 C++ 链接器都勾选 "Use float with nano printf"（-u _printf_float）。newlib-nano 默认禁用 %f 格式化，不开启的话串口只输出空白。

第三方依赖

三组外部库全部由 create_tflm_tree.py 自动生成，只需添加 include 路径，不编译任何源码：

ruy 的 instrumentation.h 自带 #ifdef RUY_PROFILER 分支，未定义该宏时回退到空类，开箱即用。

Demo 主程序

#include "CH58x_common.h"
#include "tensorflow/lite/micro/micro_interpreter.h"
#include "tensorflow/lite/micro/micro_mutable_op_resolver.h"
#include "tensorflow/lite/micro/system_setup.h"
#include "tensorflow/lite/schema/schema_generated.h"
#include "model_data.h"

namespace {

using OpResolver = tflite::MicroMutableOpResolver<3>;

TfLiteStatus RegisterOps(OpResolver& op_resolver) {
  TF_LITE_ENSURE_STATUS(op_resolver.AddFullyConnected());
  TF_LITE_ENSURE_STATUS(op_resolver.AddTanh());
  TF_LITE_ENSURE_STATUS(op_resolver.AddReshape());
  return kTfLiteOk;
}

constexpr int kTensorArenaSize = 8 * 1024;
static uint8_t tensor_arena[kTensorArenaSize] __attribute__((aligned(16)));

void RunInference() {
  const tflite::Model* model = ::tflite::GetModel(g_model_data);
  if (model->version() != TFLITE_SCHEMA_VERSION) {
    printf("Bad model version\r\n");
    return;
  }

  OpResolver op_resolver;
  if (RegisterOps(op_resolver) != kTfLiteOk) {
    printf("Op register fail\r\n");
    return;
  }

  tflite::MicroInterpreter interpreter(model, op_resolver,
                                       tensor_arena, kTensorArenaSize);
  if (interpreter.AllocateTensors() != kTfLiteOk) {
    printf("Alloc fail\r\n");
    return;
  }

  TfLiteTensor* input  = interpreter.input(0);
  TfLiteTensor* output = interpreter.output(0);

  printf("\r\n=== TFLite sin demo ===\r\n");

  float test_x[] = {0.0f, 0.5f, 1.0f, 1.5f, 2.0f, -1.0f, 3.14f};
  for (int i = 0; i < 7; i++) {
    input->data.f[0] = test_x[i];
    if (interpreter.Invoke() != kTfLiteOk) {
      printf("Invoke fail\r\n");
      return;
    }
    float y = output->data.f[0];
    printf("x=%.2f -> y=%.6f\r\n", test_x[i], y);
  }

  printf("=== Done ===\r\n");
}

}  // namespace

extern "C" int main() {
  HSECFG_Capacitance(HSECap_18p);
  SetSysClock(SYSCLK_FREQ);

  GPIOA_SetBits(GPIO_Pin_14);
  GPIOPinRemap(ENABLE, RB_PIN_UART0);
  GPIOA_ModeCfg(GPIO_Pin_15, GPIO_ModeIN_PU);
  GPIOA_ModeCfg(GPIO_Pin_14, GPIO_ModeOut_PP_5mA);
  UART0_DefInit();
  UART0_BaudRateCfg(115200);

  DelayMs(1000);
  printf("CH585M TFLite boot\r\n");

  tflite::InitializeTarget();
  RunInference();

  while (1) {}
}

要点：

• MicroMutableOpResolver<3> 模板参数在编译期确定数组大小，零堆分配
• tensor_arena[8192] 用 __attribute__((aligned(16))) 对齐
• GetModel(g_model_data) 不拷贝数据，只是指针 cast
• UART0 映射到 PA14/PA15 需要通过 GPIOPinRemap — CH585M 的 UART0 默认不在这些引脚上

编译结果

   text	   data	    bss	    dec	    hex
  71916	    844	   8240	  81000	  13c68

120+ 个算子内核全部编译，--gc-sections 自动丢弃未用代码。8KB bss 段主要是 tensor_arena，实际峰值使用约 3KB。

踩坑记录

1. flatbuffers/flatbuffers.h 找不到 — 脚本的 flatbuffers 多一层 include/ 子目录。加 -Ithird_party/flatbuffers/include。
2. ruy/profiler/instrumentation.h 找不到 — 脚本的 ruy 路径是 third_party/ruy/ruy/...。加 -Ithird_party/ruy。
3. 'fmax'/'fmin' is not a member of 'std' — newlib-nano 不提供这两个函数。加宏 TF_LITE_USE_GLOBAL_MAX 和 TF_LITE_USE_GLOBAL_MIN。
4. 'round' is not a member of 'std' — 同理，加宏 TF_LITE_USE_GLOBAL_CMATH_FUNCTIONS。
5. 串口无输出 — _write() 通过 DEBUG 宏选择串口。DEBUG=0 = UART0，DEBUG=1 = UART1。
6. 串口浮点数空白 — newlib-nano 默认禁用 %f。C 和 C++ 链接器都勾选 "Use float with nano printf"（-u _printf_float），增加约 12KB code size。
7. FLASH_EEPROM_CMD undefined — CH58x HAL 依赖 WCH ISP 库，链接加 -lISP585。

串口输出

sin(0) ≈ 0, sin(1) ≈ 0.84, sin(3.14) ≈ 0，7 个测试点全部正确。

移植成本

TFLite Micro 的架构决定了移植工作量极小：

1. 文件获取：create_tflm_tree.py 一把生成，AI 代理通过 gh codespace 全自动完成
2. 集成：删 9 个冲突文件，加 2 个 include 路径、4 个编译宏、-u _printf_float
3. 手写代码：只有 3 个平台抽象函数（共约 30 行）+ main.cc
4. 算子：不需要手动精简，--gc-sections 自动丢弃未用代码
5. 内存模型：静态 arena + GreedyMemoryPlanner，零动态分配

换模型只需改 RegisterOps() 添加对应算子注册，其余不变。

有一个现成的 sine_calcu.tflite 浮点模型（2380 字节，下载），需要量化为 int8 给 STM32 用。打开终端，装好 TF 2.21，写下一行熟悉的代码：

converter = tf.lite.TFLiteConverter.from_frozen_buffer(model_data, ...)

报错：AttributeError: type object 'TFLiteConverterV2' has no attribute 'from_frozen_buffer'。

查了一圈发现 TF 2.16+ 重构了 TFLiteConverter 的 API。新的构造函数签名是 TFLiteConverter(funcs, trackable_obj=None)，需要 concrete functions。但手里只有一个 .tflite 文件——没有 SavedModel，没有 Keras 模型，也没有原始训练代码。concrete function 从哪来？

这篇文章记录了这个问题的解法：用 flatbuffers 解析 .tflite 模型的内部结构，提取所有权重张量，在 Keras 中重建一个完全相同的模型，再走标准的 Keras → int8 量化流程。

第一步：用 flatbuffers 解析模型结构

TensorFlow 自带 TFLite 的 flatbuffers schema（tensorflow.lite.python.schema_py_generated），可以直接解析 .tflite 文件的内部结构：

from tensorflow.lite.python import schema_py_generated as _schema

with open("sine_calcu.tflite", "rb") as f:
    model_data = f.read()

model = _schema.Model.GetRootAs(model_data, 0)
sg = model.Subgraphs(0)

for i in range(sg.OperatorsLength()):
    op = sg.Operators(i)
    oc = model.OperatorCodes(op.OpcodeIndex())
    inputs = [op.Inputs(j) for j in range(op.InputsLength())]
    outputs = [op.Outputs(j) for j in range(op.OutputsLength())]
    print(f"Op [{i}]: builtin_code={oc.BuiltinCode()}, "
          f"inputs={inputs}, outputs={outputs}")

输出：

Op [0]: builtin_code=9, inputs=[0, 5, 6], outputs=[7]    ← FULLY_CONNECTED
Op [1]: builtin_code=28, inputs=[7], outputs=[8]         ← TANH
Op [2]: builtin_code=9, inputs=[8, 4, 2], outputs=[9]    ← FULLY_CONNECTED
Op [3]: builtin_code=28, inputs=[9], outputs=[10]        ← TANH
Op [4]: builtin_code=9, inputs=[10, 3, 1], outputs=[11]  ← FULLY_CONNECTED

模型结构一目了然：Dense(1→10) → Tanh → Dense(10→5) → Tanh → Dense(5→1)，一个三层 MLP。每个 tensor 的名称和 shape 也都能从 flatbuffer 中读到。

第二步：提取权重张量

所有权重都存储在 flatbuffer 的 buffer 区。根据 tensor 的名称和索引关系，定位到 6 个权重张量：

tensor_data = {}
for i in range(sg.TensorsLength()):
    t = sg.Tensors(i)
    name = t.Name().decode() if t.Name() else f"tensor_{i}"
    buf = model.Buffers(t.Buffer())
    data_len = buf.DataLength()
    if data_len > 0:
        shape = [t.Shape(j) for j in range(t.ShapeLength())]
        raw_bytes = buf.DataAsNumpy()
        arr = np.frombuffer(raw_bytes, dtype=np.float32).reshape(shape).copy()
        tensor_data[name] = arr

提取结果：

sequential_1/dense_1/MatMul   : [10, 1]   ← Layer 1 kernel
sequential_1/dense_1/BiasAdd  : [10]      ← Layer 1 bias
arith.constant3               : [5, 10]   ← Layer 2 kernel
arith.constant1               : [5]       ← Layer 2 bias
arith.constant2               : [1, 5]    ← Layer 3 kernel
arith.constant                : [1]       ← Layer 3 bias

注意 TFLite 中 FC 层的权重 shape 是 [out_features, in_features]，Keras 的 Dense 是 [in_features, out_features]，赋值时需要 transpose。

第三步：在 Keras 中重建模型

用提取的权重构建一个完全相同的 Keras 模型：

model_keras = tf.keras.Sequential([
    tf.keras.layers.Dense(10, activation='tanh', input_shape=(1,)),
    tf.keras.layers.Dense(5, activation='tanh'),
    tf.keras.layers.Dense(1),
])

# Build
_ = model_keras(np.array([[0.0]], dtype=np.float32))

# Set weights — 注意 transpose
model_keras.layers[0].set_weights([w1.T, b1])
model_keras.layers[1].set_weights([w2.T, b2])
model_keras.layers[2].set_weights([w3.T, b3])

验证 float 精度——与原 .tflite 模型对比：

x=-2.00  keras=+0.643296  tflite=+0.643297  OK
x=-1.00  keras=+0.243617  tflite=+0.243617  OK
x=+0.00  keras=+0.000132  tflite=+0.000133  OK
x=+0.50  keras=-0.001474  tflite=-0.001474  OK
x=+1.00  keras=+0.014659  tflite=+0.014659  OK
x=+2.00  keras=+0.038101  tflite=+0.038101  OK

六个测试点误差在 1e-6 级别，权重提取和重建完全正确。

第四步：Full Int8 量化

现在有了 Keras 模型，就可以走标准的 TF 量化流程：

def representative_dataset():
    for _ in range(500):
        x = np.random.uniform(-np.pi, np.pi, size=(1, 1)).astype(np.float32)
        yield [x]

converter = tf.lite.TFLiteConverter.from_keras_model(model_keras)
converter.optimizations = [tf.lite.Optimize.DEFAULT]
converter.representative_dataset = representative_dataset
converter.target_spec.supported_ops = [tf.lite.OpsSet.TFLITE_BUILTINS_INT8]
converter.inference_input_type = tf.int8
converter.inference_output_type = tf.int8

tflite_quant_model = converter.convert()

这里的关键参数：

• supported_ops = TFLITE_BUILTINS_INT8 — 要求全部算子都用 int8 内核
• inference_input_type = tf.int8 — 输入直接使用 int8，跳过 float 输入端的隐式 Quantize
• inference_output_type = tf.int8 — 输出也是 int8
• representative_dataset — 校准数据集，用于计算激活值的量化参数

量化结果

Float model: 2380 bytes
Int8  model: 2992 bytes

int8 模型尺寸不降反升——这个模型太小了（总共才 6 个权重张量，加起来不到 300 个 float），新增的 Quantize/Dequantize 算子和量化元数据开销超过了权重本身的压缩收益。对于真实规模的模型（几 MB 以上），int8 通常会缩小 3-4 倍。

量化参数：

精度验证——用 int8 推理并与原 float 模型对比：

x=+0.00  int8=+0.00683  float_ref=+0.00013  error=0.0067
x=+0.50  int8=+0.00683  float_ref=-0.00147  error=0.0083
x=+1.00  int8=+0.01024  float_ref=+0.01466  error=0.0044
x=+1.50  int8=+0.04096  float_ref=+0.02848  error=0.0125
x=-1.00  int8=+0.24919  float_ref=+0.24362  error=0.0056
x=+3.14  int8=+0.06145  float_ref=+0.05494  error=0.0065

误差在 int8 量化的正常范围（~0.01 级别）。量化后模型的函数语义保持不变。

量化前后的模型文件：

• sine_calcu_float.tflite（2380 bytes，float32）
• sine_calcu_int8.tflite（2992 bytes，全 int8 量化）

这个方法能泛化吗

这个流程的核心思路是 "从 .tflite flatbuffer 反向工程出模型结构和权重"，它适用于以下条件：

• 已知算子类型：模型只用了 TFLite 的标准内置算子（FullyConnected、Tanh、Conv2D 等），没有自定义算子
• 已知激活函数：flatbuffer 中 Tanh/ReLU/Logistic 等激活函数的代码是公开的
• 模型规模适中：权重张量数量在几十个以内，手动匹配 tensor 名称到 Keras 层的映射是可行的

对于更复杂的模型（含有分支、跳跃连接、自定义算子），手动重建会变得困难。那种场景下，更好的做法是找到原始训练代码，或者用 TF 1.x 的 tf.compat.v1.lite.TFLiteConverter.from_frozen_graph 降级处理。

这次量化工作的本质是把一个不透明的二进制模型文件变成了可操作的 Keras 对象。flatbuffers 在这里扮演了"解包器"的角色——即便 TFLite 的序列化格式是 Protobuf 或其他格式，思路一样：解析序列化格式，提取数据，重建计算图。

在单片机上跑 AI 推理是一个越来越常见的需求——设备端处理意味着低延迟、无需网络、数据隐私可控。TensorFlow Lite Micro (TFLM) 就是为此设计的：它是 TensorFlow Lite 的微控制器分支，可以在只有几十 KB RAM 的芯片上运行神经网络。

但 TFLM 的官方构建依赖 Bazel 和 Makefile，目标平台是 ARM Cortex-M 配合嵌入式工具链。如果我想在 Windows 上用 GCC 先跑通一遍，理解它的内部结构，需要做什么？

这篇文章记录了一次"模拟移植"过程：用 MinGW GCC 编译器，在 Windows 上把 TFLite Micro 编译成一个独立可执行文件，用静态内存池替代 malloc，用嵌入 C 数组替代文件系统，最终跑通 hello_world 模型的 sin(x) 推理。

移植目标与约束

真实 MCU 环境有几个硬约束：

编译器用 MinGW-w64 自带的 GCC 8.1.0，项目目录结构如下：

port/mcu/
├── platform/              # 平台抽象层（3个文件）
│   ├── mcu_debug_log.cc   # 日志输出 → vfprintf(stderr)
│   ├── mcu_system_setup.cc # 系统初始化 → 空函数
│   └── mcu_micro_time.cc  # 计时器 → clock()
├── demo/
│   ├── mcu_demo.cc        # 主程序
│   └── model_data.h       # hello_world 模型嵌入
├── mcu_config.h           # 编译配置
├── Makefile / build.ps1   # 构建脚本
└── build/
    └── mcu_demo.exe       # 最终产物 290KB

平台抽象层：三个函数打通 TFLM 与裸机

TFLite Micro 的设计把平台相关的部分抽象成了几个函数，移植时只需要实现它们。核心有三个：

DebugLog — TFLM 内部所有日志输出都走这个函数。在真实 MCU 上它应该写 UART；在模拟环境里直接用 vfprintf(stderr, ...)：

extern "C" void DebugLog(const char* format, va_list args) {
  vfprintf(stderr, format, args);
}

InitializeTarget — 芯片上电后的初始化入口（配时钟、配 GPIO 等）。模拟环境不需要做任何事：

void InitializeTarget() {
  // 真实 MCU：配置系统时钟、GPIO、UART 等
}

micro_time — 提供 tick 计数器，用于性能分析。模拟环境用 clock()，真实 MCU 用硬件定时器（SysTick）：

uint32_t ticks_per_second() { return CLOCKS_PER_SEC; }
uint32_t GetCurrentTimeTicks() { return static_cast<uint32_t>(clock()); }

这三个文件替换了 TFLM 源码中的默认实现，其余 TFLM 代码不需要任何修改。

依赖管理：flatbuffers、gemmlowp、ruy

TFLM 有三层外部依赖：

FlatBuffers — 模型解析。TFLite 模型（.tflite 文件）是 FlatBuffers 格式的序列化数据。TFLM 用 schema_generated.h（由 FlatBuffers 编译器生成）来解析模型结构。需要下载 FlatBuffers 库（约 3MB 的头文件），提供 flatbuffers/flatbuffers.h 的 include 路径。

gemmlowp — 定点运算。量化推理（int8）需要定点乘法、饱和运算等。TFLM 的 common.h 大量使用 gemmlowp::FixedPoint 模板类和配套的算术函数。这个库很小，只有头文件。

ruy — 矩阵乘法优化库。TFLM 的参考内核只引用了它的 profiler 头文件（ruy/profiler/instrumentation.h），实际不调用任何 ruy 函数。写一个空桩即可：

namespace ruy { namespace profiler {
inline void ScopeLabel(const char*) {}
}}

静态内存：Arena 分配器

TFLM 不使用 malloc。推理所需的所有内存——输入输出 tensor、中间计算结果、算子参数——全部从一个静态字节数组中分配：

constexpr int kTensorArenaSize = 3000;
uint8_t tensor_arena[kTensorArenaSize];  // 静态数组，放在 .bss 段

tflite::MicroInterpreter interpreter(model, op_resolver,
                                     tensor_arena, kTensorArenaSize);
interpreter.AllocateTensors();  // 从 arena 中分配所有 tensor

Arena 内部做了几层抽象：

• MemoryPlanner — 规划 buffer 的生命周期，决定哪些 tensor 可以复用同一块内存。默认使用 GreedyMemoryPlanner，离线计算最优复用方案。
• BufferAllocator — 执行实际的内存分配。有三种：SingleArenaBufferAllocator（可复用临时 buffer）、PersistentArenaBufferAllocator（持久分配的权重/参数）、NonPersistentArenaBufferAllocator（仅单次推理有效的 scratch buffer）。

整个分配过程发生在 AllocateTensors() 中，推理时不再有任何内存操作。

模型嵌入：.tflite 转 C 数组

没有文件系统，模型文件需要以 C 字节数组的形式嵌入代码。用 PowerShell 把 hello_world 模型（3164 字节）转换：

$bytes = [System.IO.File]::ReadAllBytes("hello_world_float.tflite")
# 输出 unsigned char g_model_data[] = {0x1C, 0x00, ...};

然后在代码中直接使用：

#include "model_data.h"

const tflite::Model* model = ::tflite::GetModel(g_model_data);

GetModel() 不拷贝数据——它只是把指针 cast 成 FlatBuffers 的 Model 结构体，零开销。

算子注册：只注册需要的

TFLM 的 MicroMutableOpResolver 采用模板参数指定最大算子数量，所有注册信息放在栈上，不触发堆分配：

using DemoOpResolver = tflite::MicroMutableOpResolver<1>;

TfLiteStatus RegisterOps(DemoOpResolver& op_resolver) {
  TF_LITE_ENSURE_STATUS(op_resolver.AddFullyConnected());
  return kTfLiteOk;
}

hello_world 模型只有一个 FullyConnected 算子（后面接 ReLU 激活，但 ReLU 被融合到 FullyConnected 的激活参数中，不需要单独注册）。链接器会把没用到的算子代码全部 strip 掉。

编译链接：41 个目标文件

最终要编译的源文件分布在几个模块中：

编译命令的核心参数：

g++ -std=c++17 \
    -fno-exceptions -fno-rtti \
    -ffunction-sections -fdata-sections \
    -DTF_LITE_USE_CTIME \
    -O2 \
    [41个.cc文件] \
    -Wl,--gc-sections -lm \
    -o mcu_demo.exe

链接后得到 290KB 的可执行文件。如果设置 -Os 并 strip 符号表，还能更小。

完整 Demo 代码

把前面各节的内容串起来，就是一个完整的推理程序。这个 demo 直接编译即可运行，不依赖任何外部文件（模型已嵌入），不触发堆分配（全部栈上或静态区）：

// mcu_demo.cc — TFLite Micro MCU Port Demo
// 模型: y = sin(x), 算子: FullyConnected + ReLU
#include <cstdio>
#include <cmath>

#include "tensorflow/lite/core/c/common.h"
#include "tensorflow/lite/micro/micro_interpreter.h"
#include "tensorflow/lite/micro/micro_log.h"
#include "tensorflow/lite/micro/micro_mutable_op_resolver.h"
#include "tensorflow/lite/micro/micro_profiler.h"
#include "tensorflow/lite/micro/system_setup.h"
#include "tensorflow/lite/schema/schema_generated.h"

#include "model_data.h"  // g_model_data[] 字节数组

namespace {

using DemoOpResolver = tflite::MicroMutableOpResolver<1>;

TfLiteStatus RegisterOps(DemoOpResolver& op_resolver) {
  TF_LITE_ENSURE_STATUS(op_resolver.AddFullyConnected());
  return kTfLiteOk;
}

// Test 1: 浮点模型推理, 验证 sin(x) 拟合精度
TfLiteStatus RunFloatModelInference() {
  MicroPrintf("\n=== Test 1: Float Model Inference ===");

  const tflite::Model* model = ::tflite::GetModel(g_model_data);
  TFLITE_CHECK_EQ(model->version(), TFLITE_SCHEMA_VERSION);

  DemoOpResolver op_resolver;
  TF_LITE_ENSURE_STATUS(RegisterOps(op_resolver));

  // MCU 关键: 静态 arena, 不调 malloc
  constexpr int kTensorArenaSize = 3000;
  static uint8_t tensor_arena[kTensorArenaSize];

  tflite::MicroInterpreter interpreter(
      model, op_resolver, tensor_arena, kTensorArenaSize);
  TF_LITE_ENSURE_STATUS(interpreter.AllocateTensors());

  TfLiteTensor* input  = interpreter.input(0);
  TfLiteTensor* output = interpreter.output(0);

  constexpr int kNumTests = 7;
  const float test_inputs[kNumTests] =
      {0.0f, 0.5f, 1.0f, 1.5f, 2.0f, 3.0f, 5.0f};
  const float epsilon = 0.10f;

  int passed = 0;
  for (int i = 0; i < kNumTests; ++i) {
    input->data.f[0] = test_inputs[i];
    TF_LITE_ENSURE_STATUS(interpreter.Invoke());
    float y_pred = interpreter.output(0)->data.f[0];
    float y_true = sinf(test_inputs[i]);
    float error  = fabsf(y_true - y_pred);
    if (error < epsilon) ++passed;

    MicroPrintf("  sin(%5.2f) = %+7.4f  |  pred = %+7.4f  |  err = %6.4f  %s",
                test_inputs[i], y_true, y_pred, error,
                error < epsilon ? "OK" : "FAIL");
  }
  return (passed == kNumTests) ? kTfLiteOk : kTfLiteError;
}

// Test 2: 1000 次连续推理, 验证 arena 内存复用稳定性
TfLiteStatus RunMultipleInvocations() {
  const tflite::Model* model = ::tflite::GetModel(g_model_data);
  DemoOpResolver op_resolver;
  TF_LITE_ENSURE_STATUS(RegisterOps(op_resolver));

  constexpr int kTensorArenaSize = 3000;
  static uint8_t tensor_arena[kTensorArenaSize];

  tflite::MicroInterpreter interpreter(
      model, op_resolver, tensor_arena, kTensorArenaSize);
  TF_LITE_ENSURE_STATUS(interpreter.AllocateTensors());

  constexpr int kIters = 1000;
  volatile float sum = 0.0f; // volatile 防编译器优化
  for (int i = 0; i < kIters; ++i) {
    interpreter.input(0)->data.f[0] = static_cast<float>(i) * 0.01f;
    TF_LITE_ENSURE_STATUS(interpreter.Invoke());
    sum += interpreter.output(0)->data.f[0];
  }
  MicroPrintf("  Ran %d inferences, checksum: %f", kIters,
              static_cast<float>(sum));
  return kTfLiteOk;
}

}  // namespace

int main() {
  tflite::InitializeTarget();

  MicroPrintf("========================================");
  MicroPrintf(" TFLite Micro — MCU Port Demo (GCC)");
  MicroPrintf(" Model: hello_world (y = sin(x))");
  MicroPrintf("========================================");

  if (RunFloatModelInference() != kTfLiteOk) return -1;
  if (RunMultipleInvocations() != kTfLiteOk) return -1;

  MicroPrintf("\n========================================");
  MicroPrintf(" ALL TESTS PASSED");
  MicroPrintf("========================================");
  return 0;
}

配套的平台抽象层三个文件：

// mcu_debug_log.cc — 日志输出
extern "C" void DebugLog(const char* format, va_list args) {
  vfprintf(stderr, format, args);  // 真实 MCU 写 UART
}
extern "C" int DebugVsnprintf(char* buf, size_t n, const char* fmt,
                               va_list vl) {
  return vsnprintf(buf, n, fmt, vl);
}

// mcu_system_setup.cc — 系统初始化
#include "tensorflow/lite/micro/system_setup.h"
namespace tflite {
void InitializeTarget() {
  // 真实 MCU: 配时钟、GPIO、UART
}
}  // namespace tflite

// mcu_micro_time.cc — 计时器
#include "tensorflow/lite/micro/micro_time.h"
#include <ctime>
namespace tflite {
uint32_t ticks_per_second() { return CLOCKS_PER_SEC; }
uint32_t GetCurrentTimeTicks() { return (uint32_t)clock(); }
}  // namespace tflite

推理验证

Demo 跑了三个测试：

Test 1 — 浮点模型推理：输入 7 个值（0.0, 0.5, 1.0, 1.5, 2.0, 3.0, 5.0），对比模型输出和标准 sin(x)，误差阈值 0.10。全部通过。

sin( 0.00) = +0.0000  |  predicted = +0.0264  |  error = 0.0264  OK
sin( 0.50) = +0.4794  |  predicted = +0.4540  |  error = 0.0254  OK
sin( 1.00) = +0.8415  |  predicted = +0.8630  |  error = 0.0216  OK
sin( 1.50) = +0.9975  |  predicted = +0.9816  |  error = 0.0158  OK
sin( 2.00) = +0.9093  |  predicted = +0.8872  |  error = 0.0221  OK
sin( 3.00) = +0.1411  |  predicted = +0.1276  |  error = 0.0135  OK
sin( 5.00) = -0.9589  |  predicted = -0.9565  |  error = 0.0024  OK
Result: 7 / 7 tests passed

Test 2 — 连续推理稳定性：循环调用 Invoke() 1000 次，验证 arena 内存复用没有累积问题。全部正常完成。

Test 3 — 性能分析：MicroProfiler 记录了每个算子的 tick 数，模拟了真实 MCU 上用硬件定时器做性能 profiling 的流程。

从模拟到真实 MCU

GCC 模拟验证了整体链路跑得通。部署到真实芯片还有几步要走：

• 算子优化：参考内核（reference/ 目录）是纯 C++ 的可移植实现。真实部署会用 CMSIS-NN（ARM）、Xtensa（ESP32-S3）、或 Ethos-U（Arm NPU）的优化版本替换。例如 CMSIS-NN 的 FullyConnected 使用 SIMD 指令，比参考实现快 4-5 倍。
• 日志通道：DebugLog 改成 UART DMA 输出，避免 printf 阻塞推理时序。
• 内存规划：用 RecordingMicroInterpreter 跑一次推理，记录实际的 arena 使用峰值，把 kTensorArenaSize 调到刚好够用。
• 模型量化：浮点模型在 Cortex-M4 上没有 FPU 的情况下很慢。用 TFLite Converter 把模型量化成 int8，推理速度能提升一个数量级，同时模型体积减半。

这次模拟移植的核心收获：TFLite Micro 的架构设计让移植到新平台非常轻量——只需要实现 3 个平台函数、提供 3 个第三方库的头文件路径、配好编译器 flag。其余代码全部是平台无关的 C++。

目标硬件是一块 Cortex-M 级别的 MCU，只有 64KB Flash 和 64KB RAM。要在上面跑一个程序：输入加速度传感器采集的 6000 个连续采样点，输出"这是震动A、震动B、还是震动C"。

这篇文章走一遍完整过程：怎么把原始震动数据变成 MCU 能理解的数字，怎么训练一个足够小的模型，怎么把它压缩到 int8 塞进 MCU，以及怎么用 C++ 写出和 Python 训练时精度一致的推理代码。

先看一眼整条链路在做什么：

六个步骤，①②③ 在 Python 端完成（训练 + 导出），④⑤ 在 C++ 端完成（MCU 推理）。下面逐个展开。

特征提取：6000 点 → 100 维

MCU 拿到的是一串 6000 个 float：[0.003, -0.012, 0.008, ...]。直接把这 6000 个数扔给神经网络行不通 — 输入太大了，MCU 算不动。

解决方案是做特征提取：把 6000 个原始采样点压缩成 100 个有意义的数字。这些数字要能描述震动信号的核心特性 — 低频有多强、波动大不大、有没有突然的尖峰。可以把它理解成一种有损压缩：扔掉不重要的细节，保留能区分三类震动的关键信息。

FFT 频域特征（64 维）

FFT 做的事情：把一段随时间变化的波形，拆成"哪些频率成分组成了这段波"。不同震动的频率分布不一样，这是 FFT 能区分它们的原因。

做法是对整条 6000 点的信号跑一次 FFT，取 64 个频率 bin 的幅度，用 log1p(x) = ln(1 + x) 对幅度做对数压缩。对数压缩的目的很简单：低频分量的幅度可能是高频的几百倍，直接送给模型，大数会把小数淹掉。取个对数，差距从几百倍缩到几倍。

fft = np.abs(np.fft.rfft(sig))        # FFT → 取幅度
feats[:64] = np.log1p(fft[1:65])       # 跳过 DC（0Hz），取 64 个 bin + 对数压缩

时域分段特征（36 维）

频域告诉模型"哪个频率在震"，时域告诉模型"震动有多剧烈、怎么变的"。

把 6000 个点切成 4 段，每段 1500 点。对每一段算 9 个统计量：

9 个特征 × 4 段 = 36 维。 加上前面 64 维 FFT，总共 100 维特征向量。

选这些特征的硬性条件只有一个：MCU 上只用加减乘除就能算。 没有 percentile()、没有 sort()、没有 log()。

for seg in range(4):
    s = sig[seg*1500:(seg+1)*1500]
    b = 64 + seg * 9
    feats[b+0] = np.mean(s)                              # 均值
    feats[b+1] = np.std(s)                               # 标准差
    feats[b+2] = np.min(s)                               # 最小值
    feats[b+3] = np.max(s)                               # 最大值
    feats[b+4] = np.sqrt(np.mean(s**2))                  # RMS
    feats[b+5] = np.max(np.abs(s))                       # 峰值
    feats[b+6] = np.sum(np.abs(np.diff(np.signbit(s)))) / len(s)  # 过零率
    feats[b+7] = np.sum(s**2) / len(s)                   # 能量
    feats[b+8] = np.count_nonzero(s) / len(s)            # 非零比

特征标准化

100 维特征算出来了，但有一个问题：不同特征的数值范围差别很大。

比如"均值"可能一直在 ±0.01 之间晃，但"能量"可能是几千的量级。直接把这些数喂给模型，数值大的特征会主导计算结果，数值小的等于没参与。

解决方法是做一次标准化（StandardScaler）：对每个特征维度，减掉均值、除以标准差。处理完后，每个维度都变成零均值、单位方差的分布。相当于把厘米、千克、秒全部统一成同一个尺度。

scaler = StandardScaler()
X_train_s = scaler.fit_transform(X_train)

# 保存 mean 和 scale — C++ 端要用完全一样的值
s_mean = scaler.mean_
s_scale = scaler.scale_
s_scale[s_scale < 1e-8] = 1.0   # 防止除零

保存 s_mean 和 s_scale 是关键动作。训练时用的 normalization 参数，推理时也必须用同一组。

模型结构

100 维输入 → Dense(16, ReLU) → Dense(8, ReLU) → Dense(3, Softmax)

三层逐级压缩：100 → 16 → 8 → 3，每层只保留最关键的信息。16 和 8 是"刚好够用且省空间"的平衡点 — 翻倍则 Flash 放不下，减半则表达力不够。

model = tf.keras.Sequential([
    tf.keras.layers.InputLayer(shape=(100,)),
    tf.keras.layers.Dense(16, activation='relu'),
    tf.keras.layers.Dense(8, activation='relu'),
    tf.keras.layers.Dense(3, activation='softmax'),
])
model.compile(optimizer=tf.keras.optimizers.Adam(0.001),
              loss='sparse_categorical_crossentropy',
              metrics=['accuracy'])
model.fit(X_train_s, y_train, batch_size=16, epochs=60,
          validation_split=0.2,
          callbacks=[tf.keras.callbacks.EarlyStopping(
              monitor='val_loss', patience=12, restore_best_weights=True)])

量化：把 float32 压成 int8

训练用的是 float32 — 每个权重占 4 字节。要在 MCU 上跑推理，需要把 float32 换成 int8，减少存储空间和计算开销。

量化和 map() 是一个道理——把数值从一个范围线性映射到另一个范围：

map(value, fromLow, fromHigh, toLow, toHigh)

量化就是把 float32 的 [r_min, r_max] 映射到 int8 的 [-128, 127]：

q = round((r - r_min) / (r_max - r_min) * 255) - 128

TFLite 的写法等价，用 scale（S）和 zero point（Z）来表达同一件事：

q = round(r / S) + Z

• S = (r_max - r_min) / 255 — 一个 int8 刻度代表多少 float32
• Z — float32 的 0 对应到 int8 的哪个值

举个例子：某层激活值在 [-1.0, 1.0] 之间，则 S = 2.0/255 ≈ 0.0078，Z = 0。r = 0.5 映射后 q = 64。

TFLite 转换器会自动算每层最优的 S 和 Z — 提供几十到几百个真实样本作为校准数据即可：

def representative_dataset():
    for i in range(0, min(len(X_train_s), 300)):
        yield [X_train_s[i:i+1]]

converter = tf.lite.TFLiteConverter.from_keras_model(model)
converter.optimizations = [tf.lite.Optimize.DEFAULT]
converter.representative_dataset = representative_dataset
converter.target_spec.supported_ops = [tf.lite.OpsSet.TFLITE_BUILTINS_INT8]
converter.inference_input_type = tf.int8
converter.inference_output_type = tf.int8
tflite_model = converter.convert()

量化前后的准确率对比：

损失不到 2%，但模型的存储空间从 7KB 降到了 1.8KB，计算从 float32 乘法变成了 int8 乘法（MCU 上快很多）。

用 C 实现特征提取

python 端的工作完成后，产出三个文件：

• vibration_model_v2.tflite — 量化后的模型（5024 字节）
• vibration_model_v2_data.h — 模型转为 C 数组，直接 #include
• scaler_params_v2.h — Scaler 的均值、标准差和量化参数

C 端的特征提取流水线：

CSV 一行 → 特征提取(DFT+时域) → StandardScaler → 量化到 int8 → 送入推理 runtime → 取最大类别

手写 DFT 的精度细节

python 端用的是 numpy 的高性能 FFT，MCU 上只能手写朴素 DFT。注意一个容易被跳过的细节 — 角度必须用 double 算：

double omega = -2.0 * 3.141592653589793 * k / len;
for (int i = 0; i < len; i++) {
    double angle = omega * i;          // ← 关键：double，不是 float
    real += sig[i] * cos(angle);
    imag += sig[i] * sin(angle);
}
feats[k - 1] = (float)log1p(sqrt(real * real + imag * imag));

为什么？6000 点的 DFT，omega * i 循环到最后一轮时 i=5999。如果用 float32 计算角度，累加误差在 10⁻³ 量级，cos/sin 之后误差被放大，最终的幅度谱和 python 端对不上。用 double 算角度，结果再截回 float，两边就对齐了。

时域特征没这个问题 — 1500 点的段内累加，float32 精度绰绰有余。

标准化 + 量化 + 推理

这步在 C++ 端复现 python 训练时的 Scaler + 量化逻辑：

for (int i = 0; i < 100; i++) {
    float s = (feats[i] - kScalerMeanV2[i]) / kScalerScaleV2[i];  // Scaler
    float q = s / kInputScale + kInputZeroPoint;                   // 量化
    if (q > 127.0f) q = 127.0f;       // clip 到 int8 范围
    if (q < -128.0f) q = -128.0f;
    input->data.int8[i] = (int8_t)lroundf(q);
}
interpreter.Invoke();

TFLM 的初始化也很轻量 — 模型只有全连接和 Softmax，两个 Op 即可：

tflite::MicroMutableOpResolver<2> resolver;
resolver.AddFullyConnected();
resolver.AddSoftmax();

static uint8_t arena[16 * 1024];   // Tensor Arena
tflite::MicroInterpreter interpreter(model, resolver, arena, 16 * 1024);
interpreter.AllocateTensors();

Python 与 C 端结果对比

同一批测试文件、同一组 Scaler 参数、同一个 TFLite 模型：

1-3% 的差异来自 numpy 的优化 FFT 实现 vs 朴素 DFT，以及 float64 和 double 中间精度的微小区别。两端结果高度一致，整条链路验证通过。

震动C 准确率偏低（~54%），原因是该类样本和震动B 的时域特征高度重叠，仅靠 100 维线性特征难以完全分开。这个方向上的改进空间在特征工程，不在模型结构。

资源占用

Flash 用了 16%，RAM 用了不到 10%。在 64KB/64KB 的 MCU 上还有充裕空间跑传感器驱动和应用层代码。

适用范围：

• 时序信号的三分类，输入几千点以内
• 特征维度 100-200，模型参数 2000-5000
• 对实时性要求不极端 — 朴素 DFT 在 MCU 上的耗时与采样点数和 bin 数量成正比，64 bin × 6000 点的计算量在秒级分类场景中足够用

如果需要更低延迟，可以对输入做降采样（如 1024 点）来减少 DFT 计算量。移植到实际 Cortex-M 开发板后，用 CMSIS-NN 的 int8 矩阵乘法内核替换 TFLM 的 Reference Fallback，可以进一步提升推理速度。

注意事项

Scaler 参数必须一字不差。 python 训练时的 mean 和 scale 要原样导出到 C 头文件。一个特征维度对不上，量化后的 int8 值直接漂到 −128 或 127 饱和，整条推理报废。

DFT 角度用 double 算。 长序列下 float32 的角度累加误差会通过 cos/sin 放大，导致幅度谱和 python 端偏差不可忽略。用 double 算角度，结果截回 float。

校准数据覆盖所有类别。 量化校准时 representative_dataset 覆盖三类震动，否则某些层的激活范围估计不准，clip 损失大。

训练前洗数据。 传感器偶发野值（读数突然飙到天文数字）会污染 Scaler 的统计。过滤掉绝对值异常的样本（比如超过 1000 的读数），用 float64 做特征提取中间计算。

防除零。 Scaler 拟合后，接近 0 的 scale_ 替换为 1.0，避免 C 头文件出现正负无穷。

在 STM32L496 上用 X-CUBE-AI 部署

前面的 C++ 推理代码先在云端虚拟机上跑通了一遍，确认整条链路（特征提取 → Scaler → 量化 → 推理）和 Python 端结果一致。实际落到 STM32L496 工程时，没有手动移植 TFLM，而是使用 STM32CubeMX 集成的 X-CUBE-AI，把同一个 vibration_model_v2.tflite 转成 ST 官方的 MCU runtime 工程代码。

CubeMX 里选择 TFLite 模型，runtime 选择 STM32Cube.AI MCU runtime。模型输入仍然是 int8[100]，输出是 int8[3]，核心网络结构没有变化。

X-CUBE-AI 生成后的计算图和训练时一致：

100 维输入 → Dense(16) → Dense(8) → Dense(3) → Softmax

这条部署路径的职责划分比较清楚：

• 特征工程仍然由固件侧 C 代码完成：6000 点原始采样 → 64 维 DFT + 36 维时域特征 → StandardScaler → int8。
• 模型推理交给 X-CUBE-AI runtime：全连接层、ReLU、Softmax 和量化参数由生成代码处理。
• 验证时同时保留一个手写 tiny_infer 路径，只用于对照每层 int8 计算，不作为最终 runtime。

真正容易出错的位置在模型输入之前。最初 C 端特征提取把时域特征数组偏移加了两次，导致 feats[64..99] 没有写入正确数据，栈上还发生了越界写。X-CUBE-AI 拿到错误的 100 维输入，预测结果自然和 Python 参考对不上。

修正后，把三类样本分别烧到 STM32L496 上运行，串口里看到的预测类别和预期类别一致：

最终验证结果：

这说明模型部署到 STM32 后，实际分类结果和桌面端验证结果一致。真正的部署检查重点是：固件端送进模型的 100 个 int8 特征必须和训练/验证端保持同一套特征工程和量化流程。

如果想看手动移植 TFLite Micro 的做法，可以看这篇更小的正弦模型示例：CH585M 上手动移植 TFLite Micro 跑 sin demo。这篇振动分类工程选择 X-CUBE-AI，是为了直接使用 ST 官方生成的 MCU runtime；手动 TFLM 和 X-CUBE-AI 两条路线的目标相同，都是把同一个量化模型稳定地放到 MCU 上运行。

如果手上有 STM32L496 开发板，也可以直接下载这份编译产物烧录验证：HEX 固件，或者用 BIN 固件 从 0x08000000 写入。烧录后打开串口窗口看日志即可，参数是 115200 8N1。

总结与改进方向

这条路线的优点是可解释、可复现，训练、特征工程、量化和 MCU 端输入都能逐项对齐；缺点也很明显，6000 点特征提取在 MCU 上跑得比较慢，最终分类效果也只能说够用。

如果想要更好的效果，可以先用 ST 的 NanoEdge AI 跑一轮基准测试。它会给出一个黑盒模型，也会把模型路线流水线暴露出来：中间用了哪些特征提取、有没有 FFT、有没有裁剪、最后用了什么模型。先让 NanoEdge AI 帮你把特征流水线试错一遍，再把这条流水线的核心思路移植成自己的代码，这样就能从黑盒工具里提炼出一个更可控的边缘 AI 模型。

一个直观的问题

想象你在整理书架。你有一堆书要放进五格书架，每本书厚度不同。如果你只是从左到右、一格一格轮流放——第一本放第一格，第二本放第二格……绕回来继续——那么很可能某一格塞满了厚书，另一格全是薄册子，五格书架看起来歪歪扭扭。

博客首页的卡片瀑布流面对的是完全一样的问题。每张卡片高度不同：有封面截图的卡片比较"厚"（300–500px），纯文字标题卡比较"薄"（150–200px）。原来的做法就是轮流往各列塞卡片，完全不看每张卡片高还是矮。运气好时各列差不多，运气差时某一列比其他列长出一大截，视觉上很难看。

一句话：轮流分配 + 高度参差不齐 = 底部必然不平。

直觉上的解法：哪列最矮就往哪列放

回到书架的例子，聪明一点的整理方式是：拿起一本书，扫一眼哪一格最空，就把书放进去。再拿下一本，继续找最空的那一格。这样不管书厚书薄，最终五格的高度一定差不多。

卡片瀑布流用的就是同一套思路。每张新卡片到来时，先看看当前哪一列总高度最小，然后塞进去。这个策略在算法领域有一个名字，叫「最短列优先」。它解决的核心矛盾是：卡片高度差异很大，而轮流分配对这种差异完全视而不见。

真正的难点：怎么知道每张卡片有多高

思路说清楚了只剩一个障碍——书是拿在手里的，厚度一眼能看到。但网页上的卡片高度在它真正渲染出来之前是未知的。封面截图加载出来多大？标题换了几行？这些都得到浏览器里实际跑一遍才知道。

所以我们采取的办法是：不猜，直接量。 每一张卡片在真正进入瀑布流之前，先被放到一个隐藏的测量区里渲染一遍。测量区宽度和真实列完全一致，卡片在里面怎么折行、图片撑多高，跟最终效果一模一样。

最初的设计是等封面图加载完再量——图片没加载时浏览器只给了一个 150px 的最小高度兜底，量出来的数字比真实值小一半以上，会严重误导最短列优先的判断。但这个串行等待带来了一个隐蔽问题：每张有封面图的卡片都要等图片加载，哪怕本地服务器图片秒开，几十张卡片累积的异步等待也会产生可感知的卡顿。排在队列末尾的卡片，要等前面所有卡片的图片全部加载完才能轮到自己，底部最后几张卡像是"卡住了"。

后来的改进是：不等待，先量再修正。 卡片渲染后立即测量当前高度（图片未加载时至少有 min-height 兜底），直接放入瀑布流。同时监听实际卡片中图片的加载完成事件——如果图片加载后实际高度变化超过阈值，就更新高度记录并重排瀑布流。这样卡片流出的速度不再被图片加载阻塞，而最终各列高度仍然收敛到精确值。

逐张处理，一张没出来下一张不许开始

每一张卡片严格按原始顺序排队进入测量区：渲染 → 量高度（不等图片） → 找当前最矮的列放进去 → 从透明渐入 → 图片后台加载完后必要时修正高度并重排。整个过程串行执行，当前卡片没有完成放置步骤之前，下一张卡片绝不开始。

这样保证了两个关键性质：

一是列高度优先基于实测数据做决策。每放入一张卡片时，先用量到的当前高度（图片可能还在后台加载），最短列优先算法拿到的是当前最准确的输入。图片加载完成后如果高度有显著变化，自动修正记录并触发重排。在本地服务器上绝大多数图片在卡片放置时已经加载完，修正触发极少。

二是卡片按原始顺序依次出现。无论文字卡还是图片卡，都不需要等封面图加载完就能先进入瀑布流，所以每张卡片流出的间隔均匀。顺序不会乱——不会出现"文字卡全部堆在上面、图片卡全部压在底下"的情况。

每张卡片独立渐入

渐入动画不是做在整个网格上，而是做在每一张卡片上。卡片在测量区完成测量后，被移入瀑布流的某一列，此时它是完全透明的。等浏览器渲染完第一帧之后，再把透明度从 0 过渡到 1，播放 0.5 秒的淡入动画。

这里有一个容易踩的坑：如果刚把卡片插入 DOM 就立刻把透明度设为 1，浏览器还没来得及画"透明"的第一帧，transition 根本不会触发——它不知道从哪开始过渡。解决办法是在设置透明度之前插入一个 requestAnimationFrame，强制浏览器先画一帧初始状态。

处理并发和分页

卡片逐个处理的逻辑用一个互斥锁保护起来，确保同一时间只会有一个处理循环在跑。如果处理过程中有新卡片到达（比如用户滚动了页面触发了分页），当前循环结束后会自动重入再跑一轮。

分页加载也被限流了：只要还有卡片在排队等待逐个处理，哨兵就不会触发下一页。等当前批次全部处理完再判断是否真的需要加载更多。这防止了卡片逐个加载时页面高度不够、哨兵一直可见、一次性把所有分页全部拉下来的问题。

手机上还有一个额外的坑：两列布局下，两列的实际高度可能差很多。原来整个瀑布流只有一个哨兵放在网格底部，它的位置由最高的那一列决定。如果左列全是文字卡（矮），右列全是截图卡（高），哨兵在右列最下方——用户滚到左列底部时看到大片空白，但哨兵还没进入视口，分页不会触发。解决方案是给每一列底部各放一个哨兵，用 IntersectionObserver 同时观察所有列的哨兵，任一列进入视口就触发下一页。这样无论各列高度差多少，用户滚到最短列的底部时也能正常加载。

效果

所有卡片按顺序逐张浮现，0.5 秒淡入，不会被封面图加载阻塞。各列高度基于 DOM 实测值做最短列优先分配，底部均匀；图片加载完成后有修正机制兜底。分页加载通过每列独立哨兵触发，手机端两列高度不均时也能正常翻页。整个流程的额外性能开销极小——每张卡片只在隐藏测量区多渲染了一次，对几十张卡片的首页来说完全无感。

现象

将 STM32 平台成熟心率采集项目交由 AI 迁移至 CH58x 蓝牙芯片，整体架构与开发规范由人工划定，AI 负责底层库函数适配与代码落地。

烧录后实测休眠电流 400μA+，同硬件上 WCH 官方低功耗示例仅 35μA，差距超过十倍。

根因：GPIO 低功耗模式底层差异

AI 迁移时直接套用 STM32 低功耗配置经验，将模拟引脚设为浮空输入，认为等效 STM32 的 Analog 模式。两类芯片此处硬件逻辑完全不同。

CH58x 不存在独立的模拟 GPIO 模式。普通数字 IO 靠输入上拉固定电平来省电，ADC 等模拟引脚需要两步配置：先设浮空输入，再调用 GPIOxDigitalCfg(DISABLE, pin) 关闭数字输入通路。两步缺一不可。

AI 只做了第一步浮空配置，完全遗漏第二步关闭数字通路，模拟引脚持续漏电，直接拉垮整机休眠功耗。

关键修复代码

全端口输入上拉（官方 Demo 基线操作，AI 未执行）：

GPIOA_ModeCfg(GPIO_Pin_All, GPIO_ModeIN_PU);
GPIOB_ModeCfg(GPIO_Pin_All, GPIO_ModeIN_PU);

心率 ADC 引脚专属配置：

GPIOA_ModeCfg(ADC_PIN, GPIO_ModeIN_Floating);
GPIOADigitalCfg(DISABLE, ADC_PIN);

如何把异常缩小到 ADC 引脚

硬件侧排查采用了拆分链路的方法。心率 ADC 通过电阻连接到外部模拟电路，休眠电流异常时，先移除这类桥接电阻，把 MCU 引脚与后级模拟网络暂时隔开。

这个动作有两个价值：

• 若功耗明显下降，说明漏电路径和这条模拟输入链路有关
• 若功耗不变，优先回到电源、时钟、无线或其他 IO 继续排查

实际现象是移除桥接电阻后功耗下降，异常范围收敛到 ADC 输入附近。随后直接测量 MCU 侧 ADC 引脚，发现休眠状态下仍接近 VCC。这个电平不符合“模拟前端已断电、ADC 输入应高阻”的预期，说明 MCU 侧仍在影响该节点。

这一步把问题从“整机低功耗异常”缩小成“ADC 引脚睡眠状态不对”。后续再回到 CH58x GPIO 配置，就能看到两个关键点：

最终处理按板级连接关系建立睡眠清单，覆盖所有连接外部模拟网络的 ADC 引脚。进入睡眠前统一执行浮空输入和关闭数字输入通路，避免普通 IO 的低功耗基线配置反过来把模拟节点拉到 VCC。

#define APP_BOARD_SLEEP_ISOLATED_ADC_PINS \
    (GPIO_Pin_2 | GPIO_Pin_3 | GPIO_Pin_4 | GPIO_Pin_5 | GPIO_Pin_12 | GPIO_Pin_13)

GPIOA_ModeCfg(APP_BOARD_SLEEP_ISOLATED_ADC_PINS, GPIO_ModeIN_Floating);
GPIOADigitalCfg(DISABLE, APP_BOARD_SLEEP_ISOLATED_ADC_PINS);

这类问题的排查顺序应先落到物理节点：拆开外部链路、测 MCU 引脚电平、确认电流变化，再回到寄存器和库函数。只看 ADC 通道号或只看当前启用通道，很容易漏掉板上真实接到模拟电路的其他引脚。

封装的三个 skill

人工逐行对比效率太低，这里采用的方法是：人搭建测试环境、封装调用接口、设定实验规则，AI 自主完成对照实验。

单轮测试完整流程

AI 按固定顺序调用三个 skill，完成一次完整功耗测试：

1. 调用电源 HTTP 接口 → 断电、延迟、上电，复位板子
2. 调用 OpenOCD skill → 烧录固件，读取日志确认启动正常
3. 延迟等待系统进入休眠
4. 运行串口读取脚本 → 采集低功耗分析仪输出并记录
5. 生成本轮实验文档：改动点、功耗数据、结论

实验规则与文档留痕

人工设定三条硬约束：

• 只能用二分法，单次仅修改一组模块
• 编译失败或功耗异常自动回退上一稳定版本
• 每轮必须输出实验文档，记录所有改动与数据

实验目标：定位官方 Demo 与 AI 移植固件之间造成 400μA 功耗差的最小代码差异。

设定完成后 AI 自主运行，夜间跑完所有对比组。次日查看日志，差异点已锁定至 GPIO 模拟引脚配置。

每轮强制输出实验文档有两个作用：

• 人工审核时可追溯每一步改动，无需猜测中间过程
• AI 上下文长度有限，跑满后重开新智能体时直接读取文档即可接续工作，无需从头重复实验

方法沉淀

这次排查的核心价值不在于"CH58x 要上拉"这个具体结论——查手册早晚能找到。

真正可复用的是这套工作模式：将物理世界的测试能力封装为标准化接口，设定实验框架和约束条件，交由 AI 自主执行对照实验。人负责设计验证方案、封装工具、审核结论，AI 负责重复劳动和数据采集。

跨平台移植场景下，AI 处理语法和业务逻辑迁移效率很高，但不同厂商 MCU 底层硬件差异容易被忽略。提前划定底层外设配置规范，搭配自动化测试闭环，才能同时兼顾开发效率与硬件指标。

站在 2026 年看，51 单片机不该继续作为新项目的默认选择。它当然还能点灯、扫按键、跑简单控制逻辑，也能在一些历史产品里继续维护；但新项目继续围着 51 做架构，很多时候已经省不了钱，只是在把工程风险往后推。

成本敏感场景已经有大量 RISC-V MCU，也有成熟的 ARM Cortex-M0/M0+ MCU。它们价格低，外设新，工具链新，C 语言支持正常，调试体验也完整得多。新项目继续用 51，常见理由是便宜、熟悉、库存稳定。放在今天，这些理由都需要重新核算。

省下来的不一定是成本

选型时最容易看到的是 BOM 成本。芯片单价、外围器件、库存替换，这些数字摆在表格里，很容易让人觉得 51 还有优势。

真正进入工程以后，成本会从另一些地方回来：

• 编译器和 IDE 落后，自动化构建、静态检查、现代调试流程都不好接。
• C99 支持不完整，代码组织、类型定义、跨平台复用都要降级。
• 内存空间割裂，code、data、idata、xdata 这类限定会进入业务代码。
• 主频和寻址模型受限，稍微复杂一点的实时逻辑就要手工抠时序。
• 外设能力弱，定时器、输入捕获、DMA、硬件滤波这类资源经常不够用。
• AI 辅助生成代码时，更容易混入不同厂商和不同编译器的旧写法。
• 维护人员越来越少，新人接手时要先学习一套过时工具链。

这些成本不会出现在芯片单价里，但会出现在调试时间、返工次数、现场问题和后续维护里。

低成本要靠大出货兑现

很多人选择 51，是为了省 BOM。这个逻辑成立有一个前提：产品能稳定量产，能形成足够大的出货量。单片机省下来的几毛钱，只有乘上足够大的数量，才会变成真正的利润。

这里有一个常见陷阱：为了省几毛钱选了余量很小的平台，后面系统稳定性、现场问题、售后返修、版本补丁把放量节奏拖住。产品出不去量，低单价优势就兑现不了。成本没有真的省下来，市场节奏也被拖过去了。

也就是说，低成本芯片本来是为大出货服务的。如果底层平台让产品不稳定，项目进不了大出货阶段，就会同时失去两件事：成本优势拿不到，销售规模也做不起来。

内存架构会污染 C 代码

51 的内存架构也是一个长期坑点。很多 51 体系把程序空间、片内数据空间、间接寻址数据空间、外部数据空间分成不同区域，常见写法会出现 code、data、idata、xdata 这样的限定。

典型 8051/8052 体系里，片内 RAM 只有几百字节。常见结构是低 128 字节支持直接寻址和间接寻址，高 128 字节只能走间接寻址，SFR 还占用另一套直接地址空间。后面扩出来的大 RAM，通常又落到 xdata 或类似扩展空间里。也就是说，真正适合快速直接访问的空间很小，剩下的空间要通过不同寻址路径访问。

这些空间不只是名字不同，访问方式、访问速度、指针模型也不同。放在 data、idata、xdata、code 里的同一份数据，最终生成的访问指令和执行成本可能完全不同。实时路径里本来只差几个机器周期，换一个内存空间就可能把时序边界踩穿。

这会让本来应该由编译器和链接器消化的细节，直接进入 C 代码设计：

• 指针类型和访问空间绑定，普通指针、远指针、通用指针的成本不同。
• 片内直接访问空间很小，大缓冲区经常被迫放进间接寻址或扩展空间。
• 不同空间访问速度不同，ISR、查表、环形缓冲、通信收发都可能被影响。
• 通用指针为了兼容多个空间，会带来额外代码体积和运行开销。
• 数据放错区域以后，访问速度、代码体积、可重入性都可能变化。
• 库函数、结构体、缓冲区、查表数据都要考虑具体内存空间。
• 代码从 51 迁到现代 MCU，或者从现代 C 项目回迁到 51，都要处理大量内存限定。

现代 MCU 上，绝大多数业务代码只需要关心 RAM、Flash、栈、堆和链接脚本边界。51 会把更底层的内存空间概念暴露到日常编码里，团队要持续为这套旧模型付认知成本，也要持续承担由访问差异带来的时序风险。

AI 会放大生态碎片

现在写代码已经大量依赖 AI 辅助。主流 ARM、RISC-V MCU 的 SDK、示例工程、论坛讨论、CI 配置和开源项目更多，训练数据更集中。51 生态的资料分散得多，厂商寄存器命名、头文件、编译器扩展、中断声明、内存限定写法都有差异。

即使把某个 51 型号的手册、示例库和头文件都喂给 AI，它也更容易犯这几类错：

• 把 Keil C51、SDCC、厂商 IDE 的语法混用。
• 把 sfr、sbit、interrupt、using、xdata、code 的约束写错。
• 用现代 C 的默认内存模型去理解 51 指针和存储空间。
• 生成看起来能编译的寄存器访问，实际 SFR 名称、位定义、初始化顺序不匹配。
• 忽略 ISR、访问空间、循环等待带来的周期成本。

AI 可以帮忙，但不能抵消生态碎片和工具链落后。资料喂得越多，它越能贴近某个型号；只要工程跨型号、跨编译器、跨旧代码风格，混写风险仍然很高。

对 STC 常见反驳的回应

如果有人拿 STC 的新型号来反驳这篇文章，通常会列出这些点：1T 架构、高主频、大容量 xdata、USB、DMA、PWM、CAN、I2S、比较器、运放、在线下载、在线仿真、低单价。这些参数都可以讨论，也确实说明 STC 在 8051 兼容产品线上做了很多增强。

这篇文章讨论的判断对象是“2026 年新项目要不要继续默认选 51 兼容路线”。“某一颗 STC 芯片能不能完成某个具体小任务”是另一个问题。这两个问题不能混在一起。

STC 的反驳里其实已经承认了产品线分层：STC8G/STC8H 面向极低成本和简单控制，STC32G/Ai8051U 进入了和 ARM Cortex-M0/M0+ 同价位竞争的区间。这个分层正好支持本文的判断：极低成本小任务可以保留特例，新项目默认选型要回到现代 MCU 的完整比较。

厂商增强外设和主频，只能解决一部分硬件指标。它解决不了这些系统性问题：

• 代码仍然要面对 8051/C51/C251/SDCC 相关方言和历史包袱。
• code、data、idata、xdata 这些内存空间概念仍然会影响代码组织。
• 旧项目、旧示例、论坛代码、厂商库、AI 生成代码之间仍然容易混写。
• 生态主流已经转向 ARM 和 RISC-V，新人、工具、CI、静态分析、调试经验都更集中在这些平台。
• 一旦项目复杂度上来，团队要为兼容路线持续付认知成本和验证成本。

xdata 变大、LARGE 模式、C251 的 NEAR/FAR/HUGE、库函数封装，都属于缓解手段。它们降低了手工分配内存空间的频率，但没有把 51 兼容生态变成普通的平坦 C 环境。只要代码还要关心编译模式、内存限定、指针模型、厂商头文件、库函数版本，认知成本就还在。

C251 + HUGE 模型可以让日常业务代码少碰 data/idata/xdata/code，这个改进可以承认。问题在于，这已经变成了一个特定芯片系列、特定编译器、特定内存模型、特定厂商资料闭环下的开发体验。工程选型要评估的正是这个闭环成本：团队成员能不能稳定复现，CI 能不能顺畅接入，静态分析能不能正常跑，第三方库能不能直接用，故障定位能不能依赖通用经验。

AI 辅助开发也是同一件事。STC 的说法是：喂完整手册、头文件、库函数说明、典型示例，生成准确率可以接受，跨型号、跨编译器时需要人工审核。这句话本身就说明了成本。现代主流 MCU 的优势在于默认资料更集中、工具链更统一、AI 更不容易把旧方言混起来。

论坛活跃、中文资料多、教学案例多，这些对入门和存量维护有价值。新产品工程还要看另一组指标：自动化构建、可移植性、团队招聘、跨平台库、长期维护、供应商切换、调试工具通用性。STC 在国内有生态，不会自动抵消 8051/80251 路线的迁移成本和专用工具链成本。

还有一个现实问题：如果一颗“现代 51”已经需要 1T、高主频、大 RAM、DMA、USB、CAN、I2S、硬件运算单元、仿真器、专用 IDE 和库函数来证明自己足够现代，那它和同价位现代 MCU 比的就不再是“51 简单便宜”这件事。它已经进入现代 MCU 的竞争区间了。

到了这个区间，选型就应该回到正常工程问题：谁的工具链更现代，谁的 C 支持更完整，谁的调试链路更稳定，谁的生态资料更集中，谁的长期维护成本更低。按这个标准看，ARM Cortex-M0/M0+ 和 RISC-V MCU 通常更干净。

所以 STC 新型号能用，不等于 51 兼容路线应该继续当默认选项。适合极低成本、强存量惯性、团队已经熟悉 STC 的项目，可以继续选。新项目从零评估时，把 51 兼容架构放在默认位置，仍然是在把历史包袱带进未来项目。

外设余量也是工程余量

很多 51 项目的核心问题来自余量太少。算力勉强够跑，定时器少一点，中断能力弱一点，IO 复用绕一点，调试工具差一点，每一项看起来都能靠软件补。

软件确实可以补，但补法经常带来新的边界：

• 没有硬件双边沿捕获，就用中断切边沿模拟。
• 没有足够输入捕获通道，就把多路信号塞进同一个 ISR。
• 没有硬件滤波，就在中断里做脉宽判断。
• 没有 DMA，就靠 CPU 搬数据。
• 没有足够调试能力，就靠日志、示波器和猜测拼现场。

这些办法在简单场景里能跑。系统规模、实时性要求、干扰环境、低功耗状态、输入路数一起上来以后，软件补硬件余量就会变成风险来源。

从控制论看工程余量

钱学森的工程控制论有一个很实用的视角：工程对象要放进反馈回路里看。产品能批量出货，单看芯片单价没有意义。扰动进来以后，系统需要被观测、被修正、被稳定拉回目标状态。

在这个视角下，CPU 主频、定时器、输入捕获、中断响应、RAM、调试链路，都是控制系统的裕度。裕度足，干扰只造成局部偏差；裕度太薄，小毛刺、低功耗切换、温漂、供应批次差异、现场安装差异，都可能被软件补丁和延迟反馈放大。

可观测性也很要命。现代 MCU 给你 SWD、trace、硬件捕获、DMA、统一内存模型，问题出现后还能定位。51 项目如果只能靠示波器、日志、猜测和反复试机，反馈链路就变长。反馈链路越长，项目调参越容易振荡：修一个现场问题，压出另一个边界；加一个过滤，漏掉另一个脉冲；补一个中断状态，挤掉别的实时任务。

可控性同样重要。硬件资源够，设计可以选择硬件捕获、硬件滤波、DMA 搬运、独立 ISR、低功耗状态保持。资源不够，软件只能把多个实时职责塞进同一条中断路径，控制输入就变少了，回旋空间也变小了。

所以从控制论看，一颗便宜芯片如果降低了系统的可观测性、可控性和稳定裕度，它的低单价只是一段开环计算。闭环成本会在调试、返修、延期和维护里补回来。

技术债会持续计息

工程要给自己留余量。算力余量、外设余量、定时器余量、调试余量，看起来都不直接出现在 BOM 上，但被省掉以后，不确定性不会消失，只会转成风险。

风险再拖下去，就会变成技术债。每一次改需求，要先问还能不能塞下；每一次加功能，要先问中断还能不能扛住；每一次现场异常，要先怀疑时序边界又被踩到；每一次换人维护，都要重新解释工具链和架构限制。

技术债的麻烦在于它会持续计息。早期为了省一点硬件余量，后面会用更多软件复杂度、测试成本、沟通成本和现场成本偿还。

新项目别默认选 51

历史 51 产品不必全部立刻重做。存量项目有认证、库存、产线、代码和售后约束，继续维护很正常。

但新项目不该再把 51 放在默认位置。默认选型应该从现代 RISC-V MCU、ARM Cortex-M0/M0+ MCU 或同级别现代单片机开始评估，再根据供货、成本、外设、功耗、工具链和团队经验收敛。

如果一个项目需要稳定输入捕获、低功耗唤醒、复杂通信、现场可调试性、长期维护，51 的低单价很可能抵不过后面的工程成本。工程系统真正需要的是余量。余量买在前面，是成本；余量省在前面，后面就会变成不确定性的风险和滚起来的技术债。

这是一个中途接手的项目。原方案基于 51 单片机，6 个电机各有 2 路霍尔反馈信号，一共 12 路外部脉冲，最初直接用 GPIO 下降沿中断捕获；后来现场发现输入容易受到干扰，我在这个基础上引入了软件脉宽过滤。继续排查计数抖动问题时，才发现这个过滤方案本身也受限于既有硬件资源和中断实时性。

脉宽过滤本身没有复杂：下降沿来了先记时间，上升沿来了再算宽度；宽度够，就提交一次有效脉冲。麻烦出在要捕获的是微秒级脉宽，留给 ISR 响应和软件切边沿的时间预算很短。

高电平 ─────┐      ┌───── 高电平
             │      │
低电平       └──────┘
             A      B
           下降沿   上升沿

真正的问题在实现方式。读者如果习惯了资源完整的 MCU，可能会默认 GPIO 可以直接开双边沿触发；但部分 51 单片机的中断能力比较受限，只能配置单边沿，或者不同 IO 的边沿能力受限。硬件没有给每一路输入独立的双边沿捕获、脉冲计数或去抖资源时，软件只能在对应 GPIO 中断 ISR 里模拟：A 点进中断，记录时间，把这个 IO 切到等 B 点；B 点再进中断，计算脉宽，再切回等 A 点。

12 路输入挤在几个中断里

如果只有一路信号，这个软件状态机已经依赖 ISR 响应速度。脉宽长到毫秒级时，软件通常还有余量；脉宽压到微秒级时，余量会迅速消失。

12 路 IO 不会都在同一个 port 上。更常见的情况是：多个 port 各有自己的中断入口，每个 port 内的多个 IO 共用同一个中断服务函数。每一路又都要在这个 ISR 里模拟双边沿，实时性压力会放大：

• ISR 先读一次中断标志寄存器。
• 软件逐位判断是哪一路 IO 触发。
• 每一路都有自己的“等下降沿 / 等上升沿”状态。
• 每一路都要在 ISR 里切换触发模式。

这相当于在低主频 51 单片机上，分散在几个 GPIO 中断里，用软件模拟 12 个小型输入捕获外设。

漏边沿发生在哪里

理想时序是：

下降沿 A
MCU 进入 ISR
软件切到等上升沿
上升沿 B
MCU 再进 ISR
软件验证脉宽

实时性不够时，时序可能变成：

下降沿 A
上升沿 B
MCU 才进入 ISR

这时同一个 IO 的中断标志只有一个 bit。它只能表示“这个脚触发过”，不能表示“这个脚连续触发了两次”。软件已经拿不到 A 和 B 的完整历史，这个真实脉冲就可能被当成毛刺丢掉。

多个 IO 共用同一个 port 的中断入口不一定有错。风险来自“多个 IO 共用 ISR + 12 路软件双边沿 + 低主频 + 单 bit 标志”。只要其中一路边沿间隔接近或短于 ISR 最坏响应时间，软件模拟的双边沿过滤就没有足够时间完成状态切换。脉宽越短，这个风险越明显。

受控脉冲实验

为了验证软件边沿捕获的实时性，可以用受控信号源产生固定数量、固定脉宽的脉冲序列，再检查 MCU 侧捕获数量是否完整。

这次测试使用 10 个脉冲作为一组手动触发序列：9 个合法脉冲宽度为 260us，1 个非法脉冲宽度为 240us。软件过滤阈值设为 >= 250us 有效。触发前后保持低电平。

少量触发时，计数结果基本符合预期，说明边沿切换和脉宽判断在低压力条件下可以工作。重复触发多次后，打印日志出现了两路计数分叉：

当 FBZ = 55 时，按当前显示滞后关系计算，理论 FB 有效计数为：

(55 + 1) * 9 - 1 = 503

实测结果为：

LM FB = 512
RM FB = 503
FBZ   = 55

RM 与理论值一致，LM 多计 9。这个结果说明至少有一路在长时间重复触发后发生了误计数。

这组实验暴露的是阈值附近的实时性余量不足。合法脉宽 260us、非法脉宽 240us，都只距离 250us 阈值 10us。多个 IO 共用同一个中断服务函数，并在 ISR 内软件切换边沿模式时，中断响应延迟、处理顺序差异、边沿模式切换延迟都会改变测得脉宽。部分 240us 非法脉冲可能被测成有效脉冲，最终表现为多计数。

两路结果不同也很有参考价值。共享 ISR 下，不同 IO 接收同一组测试脉冲，实际软件捕获条件并不完全一致。排在 ISR 后面的分支、和其他 IO 同时触发的分支，会承受额外的软件处理延迟。

提主频以后还要看 ISR 开销

第一反应通常是提高 CPU 主频。主频从 24MHz 提到 40MHz 后，指令执行变快，中断响应也会变短，理论上可以给软件双边沿捕获争取更多余量。

但这次测试又暴露了另一个细节：时间戳换算本身也在 ISR 路径里。24MHz、12T 模式下，Timer11 原始计数频率为 2MHz，1 tick 等于 0.5us，换算成微秒只需要除以 2。40MHz、12T 模式下，Timer11 原始计数频率为 3.333MHz，1 tick 等于 0.3us，换算成微秒会变成 raw * 3 / 10。

放在 51 单片机上，32 位除法和取模很重。CPU 主频提高带来的收益，可能被 ISR 内的实时换算吃掉一部分。软件捕获路径里，最贵的地方不该放在边沿到来的瞬间。

后续把 ISR 改成直接使用 Timer11 原始 tick：

rise_tick = T11_raw
width_tick = now_raw - rise_tick

阈值在编译期换算成 tick 后再比较：

40MHz / 12T: 1 tick = 0.3us
250us = 833.33 tick
向上取整后，阈值取 834 tick

这样 ISR 热路径只剩下读计数器、uint16_t 减法、uint16_t 比较和计数更新。微秒单位只用于调试打印，不再参与实时判定。

再次测试后，260us 合法脉冲被测到 261264us，240us 非法脉冲被测到 241244us，并稳定进入 reject 统计。这个结果把方向指得很清楚：信号源精度可以信任，单纯提高主频仍然不够，实时路径里的昂贵换算必须移出去，阈值比较要回到原始 tick 域。

硬件捕获和软件模拟的差别

有些 MCU 的定时器或专用输入捕获外设可以直接做这些事：

• 硬件双边沿捕获。
• 硬件脉冲计数。
• 输入滤波或去抖。
• 捕获时刻锁存。

这些能力的价值在于：边沿先由硬件抓住，软件晚一点处理也不会立刻丢历史。

用 GPIO 中断软件模拟时，边沿历史只剩一个标志 bit。软件来晚了，硬件不会帮你补记录。

工程结论

这个问题不适合只靠调脉宽阈值解决。阈值只能决定什么宽度算有效，不能恢复已经错过的边沿。

如果系统没有足够的定时器、输入捕获通道或带滤波能力的专用 IO，那么软件模拟双边沿必须接受一个边界：真实脉冲宽度要明显大于 ISR 最坏响应时间。微秒级脉宽已经接近这个边界，不能只按普通 GPIO 中断来理解。

如果脉宽确实这么短，工程上只有几条路：提高 CPU 主频，换取更短的中断响应时间；减少每个中断服务函数里软件模拟的输入路数；或者把关键输入迁到硬件双边沿捕获、定时器输入捕获、硬件计数和硬件滤波资源上。

当 12 路信号都依赖 51 的 GPIO 中断软件模拟双边沿，漏边沿就不再是偶然 bug，它是硬件资源不足和软件实时性边界叠加后的自然结果。

一点个人观点

站在 2026 年看，51 单片机不该继续作为新项目的默认选择。成本敏感场景已经有大量 RISC-V MCU，也有成熟的 ARM Cortex-M0/M0+ MCU：价格低，外设新，工具链新，C 语言支持也正常。

51 的问题不只是主频低。很多型号 C99 支持不完整，编译器、调试器、工程体系都停在旧时代，外设能力也很弱。最后省下来的物料成本，很容易变成中断实时性、工具链兼容、维护成本和现场调试成本。

工程要给自己留余量。算力余量、外设余量、定时器余量、调试余量，看起来都不直接出现在 BOM 上，但被省掉以后，不确定性不会消失，只会转成风险。风险再拖下去，就会变成技术债，持续计息，后面每一次改需求、查现场、补兼容都要还。

这个 Bootloader 的核心思路是把外挂 W25Q Flash 做成固件镜像池和启动决策区。Bootloader 复位后先读取外部 Flash 中的启动选项，再选择目标固件、完成校验、提交到内部 APP 运行区，最后跳转到 APP 向量表启动。

这样做的直接收益是：OTA 链路可以分包、断点续写或分多次会话完成；内部 Flash 只在固件头、固件本体、启动选项都通过校验后才被擦写。Bootloader 不需要在接收过程中反复动内部 Flash，APP 区也不会因为半包数据变成不可启动状态。

升级目标

这个项目解决的是小容量 MCU 做 OTA 升级时的一个基本矛盾：内部 Flash 空间有限，升级链路又不适合把数据直接写进运行区。

内部 Flash 被划成两块：

• Bootloader 固定放在起始位置，负责初始化外部 Flash、读取启动选项、选择目标固件、校验固件、擦写 APP 区、跳转 APP。
• 用户 APP 放在后面的运行区。Bootloader 只在确认外部 Flash 中的目标固件有效后才覆盖这一段。

外挂 Flash 承担三类状态：

• 启动选项：记录本次要从外部 Flash 的哪个固件槽位引导启动。
• 固件槽位：保存用户、DFU、工厂、升级、备份、临时等不同用途的固件入口。
• 完整性信息：固件头和 CRC32 放在外部 Flash 中，Bootloader 从这里判断能否提交到内部 Flash。

内部 Flash 因此只保留“当前可运行版本”。外部 Flash 保留“候选版本”和“启动意图”。

外挂 Flash 保存可启动固件

升级包先进入外挂 Flash。Bootloader 重启后先把这份数据视为候选固件，再按固定顺序判断它能否成为本次启动目标：

• 先读固件头，检查头部自身的 CRC32。
• 再检查固件大小，确认不会超过内部 APP 区。
• 接着按分块方式读取外部 Flash，计算固件本体 CRC32。
• 只有固件自带 CRC32 和本地计算结果一致，才允许提交到内部 APP 运行区。
• 如果内部 Flash 里已有同样 CRC32 的 APP，则跳过重复写入。

这套流程把“固件已写入外部 Flash”和“本次启动采用该固件”分开。外部 Flash 中可以长期保存多份固件镜像，Bootloader 每次复位后根据启动选项选择其中一份，再用完整性校验决定能否引导启动。

这里的启动路径是：外部 Flash 保存固件镜像和启动意图，Bootloader 在复位后选择目标镜像，校验后写入内部 APP 运行区，再交给 APP 向量表启动。外挂 Flash 提供可重读、可校验的固件来源，真正的控制权交接发生在内部 APP 运行区。

启动选项做成主备记录

外挂 Flash 里不只保存固件，也保存启动选项。项目里有主记录和备份记录，两份记录都有 CRC32。

Bootloader 启动后先读两份启动选项：

• 主记录有效时使用主记录；备份记录损坏时用主记录覆盖备份记录。
• 主记录损坏但备份记录有效时使用备份记录，并回写主记录。
• 两份都无效时不执行升级决策，最后尝试跳转已有 APP。

启动选项里最重要的是启动标志。它把外部 Flash 中的固件槽位分成几个启动目标：

• 用户固件：正常运行路径。
• DFU 固件：进入设备固件升级能力。
• 工厂固件：保留出厂或恢复路径。
• 升级固件：把外部 Flash 中的新固件提交到内部 APP 区并作为本次启动目标。
• 临时固件：用于一次性验证或特殊启动。

每次启动选项被修改后，Bootloader 会重新计算 CRC32，再写回主备两份记录。这个动作让启动意图本身也具备掉电后的可恢复能力。

固件槽位保留回退余地

外挂 Flash 的价值不只在“比内部 Flash 大”。它让 Bootloader 可以把不同生命周期的可启动固件分开放。

用户固件是日常运行目标，DFU 固件是升级能力本身，工厂固件提供恢复入口，升级固件作为待提交版本，备份固件用于保留旧版本，临时固件用于不改变默认启动策略的试运行。

这些槽位让 Bootloader 的职责从“把一个 bin 写进 APP 区”扩展成“根据启动选项选择一个外部 Flash 固件槽位，再决定是否引导启动”。提交成功后，启动选项可以回到默认用户启动模式；需要保持工厂模式时，也可以让工厂启动标志继续保留。

这里的重点是责任分层：

• 外部通信负责把固件写入外挂 Flash 的指定槽位。
• Bootloader 负责读启动选项、验证槽位里的固件、提交到内部 Flash 并完成引导。
• APP 只负责运行自身逻辑，不参与擦写自己的运行区。

这种分层减少了在线升级时最危险的耦合：业务 APP 不需要在自身运行期间覆盖自身所在的内部 Flash。

写内部 Flash 前先收口风险

内部 Flash 擦写是这个流程里风险最高的动作，所以它被放在最后。

项目中的写入路径有几个保护点：

• 写入前先完成头部校验、大小校验和固件本体校验。
• 擦除内部 APP 区前先解锁 Flash，写完后及时加锁。
• 外部 Flash 到内部 Flash 的复制使用固定大小缓冲区分块完成，避免一次性占用过多 RAM。
• 跳转 APP 前关闭 SysTick、清中断挂起状态、反初始化 HAL，并设置 APP 的主栈指针。

最后一个细节很重要。Bootloader 跳到 APP 属于固件控制权交接。跳转前如果外设、中断、SysTick 状态没有收干净，APP 会带着 Bootloader 的运行现场启动，后续问题会很难定位。

适用边界

这类外挂 Flash Bootloader 适合几种场景：

• MCU 内部 Flash 无法同时容纳两个完整 APP。
• 升级链路可能分包、断连或跨多次会话完成。
• 设备需要保留工厂固件、DFU 固件、备份固件等恢复路径。
• Bootloader 需要在启动阶段从多份外部 Flash 固件中选择目标版本。

它也有明确代价：

• 系统多依赖一颗外部 Flash，硬件和驱动初始化必须可靠。
• 外部 Flash 的分区表、启动选项和上位机写入规则必须保持一致。
• 如果启动选项和固件槽位的状态机没有定义清楚，升级成功、回退、临时启动会互相影响。
• Bootloader 必须足够小、足够稳定，后续升级机制都依赖它。

这个项目的核心设计可以概括成一句话：外挂 Flash 保存可校验的固件镜像和启动选项，Bootloader 在启动阶段选择目标镜像并引导启动。内部 Flash 只承接最终运行结果，外挂 Flash 承接 OTA 传输过程、版本选择和恢复路径。

串口接收看似只是“收到字节再读出来”，实际工程里会遇到短命令、连续数据流、主循环忙碌、协议解析耗时不稳定等情况。接收路径设计不好，就容易出现丢字节、乱序、短包延迟和偶发错包。

串口接收是嵌入式系统的基本输入路径。本文记录一种从简单轮询接收到 DMA circular + IDLE + HT/TC + FIFO 的演进思路，重点是把硬件接收、DMA 搬运、中断触发、软件缓冲和用户层解析拆开，让每一层职责清楚、边界可测。

阶段1：轮询寄存器

【快递站类比】

最开始的快递站很原始。老板每隔几分钟跑到门口看一眼，有快递就自己拿进来，没有快递就回去继续干别的活。

这个办法在快递很少时能用。一旦老板在里面算账、接电话，门口来了好几车快递没人接，快递员等不住就走了，包裹也就丢了。

【技术解耦与实现】

对应到串口接收，轮询就是主循环反复检查接收标志，发现有数据后读取数据寄存器。它的优点是直观，适合 bring-up、低速调试和最小可用验证。

问题在于 CPU 的主循环不可能长期只服务串口。只要轮询间隔变长，外设接收寄存器就可能来不及被读取，后续字节进入时触发溢出。轮询阶段可以用回环测试做最小验证：PC 持续发送随机字节，设备原样回显，PC 端逐字节比较。如果低波特率回环测试都不稳定，先检查串口配置、引脚复用和基础读写路径。

阶段2：字节中断

【快递站类比】

后来快递站在门口装了门铃。快递员到了不用等老板巡逻，按一下门铃，老板出来签收。

这比老板反复跑门口省力很多。但到了双11，门铃一直响，老板每隔几秒就被叫出去一次，里面的分拣、记账、发货全都做不动。

【技术解耦与实现】

字节中断把“等待数据”的成本降下来。串口收到一个字节后触发中断，CPU 在中断服务函数里读出数据寄存器。

它的限制来自中断频率。波特率升高后，每个字节都触发一次中断，CPU 会被大量小中断压住。中断里只应该做最小动作：快速取走字节、放入轻量缓冲、退出。协议解析、打印、大块复制都不应该压到这个路径里。

这一阶段继续用回环测试压测，但要逐步提高波特率，并让主循环同时做轻量任务。通过标准不能靠肉眼看到有回显，必须看 PC 端校验：长度一致、内容一致、顺序一致、设备不中断运行。

阶段3：普通 DMA

【快递站类比】

接着，快递站在门口放了一个大箩筐。快递员不用按门铃，也不用等老板，直接把包裹放进箩筐。

箩筐满了，老板再一次性搬进去。这样老板不用每个包裹都跑一趟。但老板把箩筐搬进屋、倒空、再放回门口的这段时间，新来的快递又没地方放。

【技术解耦与实现】

普通 DMA 让外设把接收到的字节直接搬到内存。CPU 不再为每个字节进入中断，只需要等一块 DMA buffer 写满后再处理。

这个阶段的结构通常是一块固定 RX buffer：启动一次外设到内存的 DMA 接收，DMA 写满后触发完成中断，CPU 处理这段内存，然后重新启动下一次 DMA。它解决了“每字节中断”的问题，但带来了重启空档。DMA 完成后，如果 CPU 处理和重新启动接收不够快，中间进入的字节仍然可能丢失。

回环测试要覆盖随机长度数据块，尤其是短包、长包和接近 buffer 大小的数据块。这里常见问题有两个：只处理满 buffer，短包一直等不到处理；DMA 完成后重启太慢，连续输入时出现空档。

阶段4：双缓冲区

【快递站类比】

快递站又放了两个箩筐。A 箩筐满了，老板搬 A；快递员马上改往 B 箩筐里放包裹。B 满了，再切回 A。

这解决了“搬箩筐时门口没地方放”的问题。但如果快递员只放了两个包裹就走了，箩筐永远装不满，老板可能一直等着“满了再搬”，屋里的人也迟迟拿不到这两个包裹。

【技术解耦与实现】

双缓冲区把接收和处理拆开：DMA 当前写 buffer A，A 满后切到 buffer B，CPU 处理 A；B 满后再切回 A。这个模型对固定长度数据块很清楚，可以减少普通 DMA 重启期间的接收空档。

它仍然没有解决变长数据。串口经常是字节流，数据不一定刚好填满 buffer。一段命令发完后，如果 buffer 没满，系统也需要及时处理这段数据。另一方面，如果上层处理长期慢于输入速度，两块 buffer 最终都会被占住，后续数据仍会被覆盖或丢弃。

这一阶段的回环测试要覆盖两类输入：刚好填满 buffer 的连续块，用来验证 A/B 切换；随机长度短包，用来验证未填满 buffer 能否被及时提交。出现整块丢失、A/B 顺序颠倒或短包长时间不回显，都说明双缓冲状态管理还有问题。

阶段5：空闲中断（IDLE）

【快递站类比】

快递站又装了一个红外线感应器。快递员往箩筐里放完东西，走了，门口安静下来，感应器就通知老板。

这样不管箩筐有没有满，只要快递员这一波已经放完，老板就能马上把已有包裹搬进去，不用傻等箩筐装满。

【技术解耦与实现】

IDLE 中断用于识别串口线上出现空闲。对变长数据来说，它提供了一个很重要的处理时机：这段输入暂时结束了，可以把 DMA 工作区里已经收到的数据搬走。

它不负责解析协议，也不判断这一段是否完整业务帧。它只解决一个底层问题：DMA buffer 里有一段新增字节，现在可以提交给后面的软件缓冲。实现上，驱动通过 DMA 当前写入位置和上次已处理位置，计算新增范围，再把这段数据搬到后续队列。

实现细节： 常见 HAL 写法会用 DMA 剩余计数换算写指针，例如 buffer_size - dma_remaining_count。这个代码只是在定位写位置，核心设计仍然是“IDLE 触发搬运，后续缓冲承接数据”。

IDLE 的限制也很明确：它依赖“空闲”。如果上位机连续发送，没有足够长的停顿，IDLE 就不会及时触发。持续流输入需要新的搬运节点。

阶段6：循环 DMA + HT/TC：兼顾连续流和短包

【快递站类比】

最后，快递站把两个箩筐换成了一条循环传送带。快递员不停往传送带上放包裹，传送带走到一半，系统提醒老板搬一段；走到末尾，再提醒老板搬一段。

如果快递员放一会儿就走，红外线感应器也会提醒老板来搬。这样一来，快递断断续续也能及时处理，快递连续不断也能按传送带位置分段搬走，传送带不需要停下来换箩筐。

【技术解耦与实现】

循环 DMA 让 DMA 写到缓冲区末尾后自动回到开头继续写。它省掉了显式 A/B 双缓冲状态，也减少了普通 DMA 反复重启带来的空档。

仅靠 IDLE 还不够，因为持续流没有空闲。因此循环 DMA 通常配合两个固定节点：半传输中断 HT 和传输完成中断 TC。HT 表示 DMA 写到缓冲区一半，TC 表示写到末尾。IDLE、HT、TC 都进入同一个搬运逻辑：计算从上次位置到当前位置之间新增了哪些字节，把它们交给后面的软件层。

实现细节： 在 HAL 工程里，通常会启用 DMA_IT_HT 和 DMA_IT_TC，再让 DMA IRQ 和 USART IDLE IRQ 走同一个“计算新增范围并搬运”的函数。函数名不重要，职责必须统一。

HT/TC 等价于把一段循环内存切成稳定观察点。物理上只有一块环形 DMA buffer，逻辑上获得了类似乒乓缓冲的效果：前半段写满搬一次，后半段写满再搬一次。配合 IDLE 后，短包、变长包和连续流都能触发搬运。

这一阶段最需要连续随机流压测。PC 端不要一帧一停，要持续发送随机数据，让串口线上尽量少出现空闲。通过标准是回显序列完全一致，正常容量内丢弃计数不增长，超过设计能力时必须能看到明确的溢出统计。

阶段7：软件 FIFO：解耦接收和解析

【快递站类比】

老板把传送带上的包裹搬进来后，没有马上逐个拆包处理。他把包裹先放进后面的大仓库。

业务部门有空了再去仓库慢慢分拣。哪怕业务部门临时去开会，前面快递站也可以先把包裹囤住，不会因为后面处理慢就让门口丢件。

【技术解耦与实现】

FIFO 的职责是把实时接收和业务处理解耦。DMA buffer 是硬件接收工作区，容量小，且持续被 DMA 写；FIFO 是软件队列，保存已经脱离 DMA 工作区、等待上层消费的字节流。

这条边界很重要：

• DMA buffer 负责临时接住硬件输入。
• 中断处理负责按 IDLE、HT、TC 节点把新增字节搬走。
• FIFO 负责保存有序字节流，并吸收短时间突发。
• 用户层负责协议解析、校验、组包、丢帧恢复等语义。

驱动层不应该解析协议，不应该替用户清理业务缓存，也不应该假装 FIFO 永远够用。FIFO 满时必须累计丢弃字节数和队列溢出次数。静默覆盖是灾难：上层只会看到偶发错包、乱序或解析失败，真正的压力来源消失了。溢出计数把“用户消费速度跟不上”暴露出来，这是防御性编程的一部分。

回环测试在这一阶段要验证保序和可观测性。PC 端持续发送随机流，设备从 FIFO 取一小段再回显。只要容量没有越界，回显就应该长度一致、内容一致、顺序一致。容量越界时，可以丢，但必须有溢出计数，测试报告也要明确标记为压力超过设计范围。

阶段8：直接读取循环缓冲：省内存但边界更紧

【快递站类比】

如果快递站租金很贵，老板可能想把后面的大仓库拆掉。这个时候不能只拆仓库，还要把门口的循环传送带加长，让它本身能临时堆更多包裹。

这样一来，传送带既负责接快递，也兼任临时仓库。业务部门不再去仓库拿包裹，直接从传送带上拿。省掉了“老板把包裹从传送带搬到仓库”这一步。

这样省地方，但要求业务部门动作很快，还要时刻知道自己拿到哪里了。一旦拿慢了，传送带转一圈，新的包裹就会盖掉旧包裹，之前没拿走的东西就丢了。

【技术解耦与实现】

走到循环 DMA 后，还可以取消独立软件 RX FIFO，但前提是把循环 DMA buffer 配得足够大。循环 DMA buffer 本身就是环形内存：DMA 写指针持续前进，走到末尾再回到开头。只要驱动再维护一个软件读指针，就可以把这段 DMA buffer 直接封装成 FIFO。

这个设计少一次从 DMA buffer 到外部 FIFO 的搬运，也省掉一块独立 FIFO RAM，适合资源很紧、接收处理足够快、接口可以统一封装的工程。代价是 DMA buffer 同时承担两个职责：硬件接收工作区和用户可读队列。读写边界必须清楚。

最低要求包括：

• DMA buffer 要按最坏消费延迟加长，不能沿用很小的临时接收缓冲。
• 可读长度必须由 DMA 写位置和软件读位置计算。
• 读取函数必须处理回绕，不能假设数据连续。
• 写位置追上读位置时，必须判定覆盖风险。
• 溢出统计必须保留，不能把覆盖伪装成随机错字节。

外部 FIFO 和加长 DMA buffer 后直接读取没有绝对高低。外部 FIFO 的职责边界更清楚，可观测性更好；DMA 直读更省搬运和 RAM，但读写指针、覆盖判断、缓冲区长度估算和压力测试都要更严谨。

发送侧延伸：TX FIFO

【快递站类比】

收快递解决后，发快递也会遇到类似问题。业务部门都想把包裹交给前台寄出，但门口只有一辆车，一次只能发一批。

更稳的做法是把待发包裹先排进出库队列。车空了就装下一批，装完再发下一批。业务部门只负责交货，前台负责按顺序发出。

【技术解耦与实现】

发送侧通常会有 busy 标志，并在发送完成回调里清除。简单回显可以直接判断空闲后启动 DMA 发送，但多个模块同时打印或发送协议帧时，调用方会被迫关心“现在能不能发”。

TX FIFO 可以把发送入口统一起来：外部模块只写入待发送数据，串口发送驱动在空闲时从 TX FIFO 取一段启动 DMA，发送完成中断清 busy 并继续取下一段。这样发送侧也形成同样边界：用户只负责投递，驱动负责按串口单通道特性串行发出。

回环测试可以同时验证 RX FIFO 和 TX FIFO。PC 端看到的仍然应该是原始随机流，顺序不能乱，内容不能变，两个 DMA 通道的状态不能互相破坏。

回环测试与可观测性

每一层优化都应该接受同一个外部判据：PC 端持续发送随机数据，设备原样回显，PC 端负责校验。这样测试目标不会随着实现变化被稀释。

推荐测试分成几组：

• 固定长度短包：验证基础收发和中断入口。
• 随机长度包：覆盖变长数据和 DMA 批量搬运。
• 连续随机流：减少空闲时间，验证 HT/TC 能否补上单纯 IDLE 的缺口。
• 逐步提高波特率：观察系统从稳定到接近极限的过程。
• 加入主循环负载：验证用户处理变慢时 FIFO 是否能吸收短时间突发。

通过标准要明确：

• PC 端发送字节数和回显字节数一致。
• 回显内容和发送内容逐字节一致。
• 字节顺序不乱，不重复，不跳号。
• 设备不中断运行，发送完成回调能持续推进。
• 正常压力下队列溢出计数不增长。
• 超过设计容量时，溢出计数增长，测试报告明确标记为压力越界。

随机流压测会打破“刚好按包发送”的理想条件。真实系统里，上位机可能连续发送，也可能短包密集出现，还可能在任意位置停顿。随机长度、随机内容、逐步提高波特率，能更早暴露边界错误。

适用边界

DMA circular + IDLE + HT/TC + FIFO 适合做通用串口接收底座，特别适合变长数据、突发输入和上层处理时间不稳定的场景。

它仍有容量上限：

• FIFO 满时仍然会丢数据，工程需要统计并暴露这个事件。
• 驱动层只搬运字节，不替协议层判断帧边界和恢复策略。
• DMA 缓冲区太小会增加 HT/TC 中断频率；如果取消独立软件 FIFO，DMA 缓冲区还要承担仓库职责，长度必须按最坏消费延迟估算。
• 用户层长期消费不足时，任何缓冲都会被填满，最终必须靠流控、限速或协议重试解决。

这套设计包含 DMA 搬运，也包含清楚的接收链路分层：硬件用 DMA 快速落内存，中断用 IDLE/HT/TC 找搬运时机，FIFO 保存已经脱离 DMA 工作区的数据，用户层按自己的协议节奏处理。

本文由 AI 辅助生成，可能存在错误或遗漏，请以实际资料和官方文档为准。

这是一个面向电调天线现场维护的手持控制终端，对接 UMTS（3G）基站 Node B 的 Iuant 接口和 RETAP 协议标准。软件部分负责把底层协议能力做成一台可以独立使用的本地工具：扫描总线设备、选择目标天线、执行校准、设置倾角、读取设备信息、从存储卡下发配置和固件。

这个项目不只是做菜单。菜单只是操作入口，软件部分还要把标准协议对接、多设备扫描、地址绑定、文件维护、USB 存储模式和现场反馈串成一套可用流程。

下面是完整的仿真界面总览，覆盖扫描、主菜单、校准、倾角、信息、文件、设置和英文界面。

脱敏说明：本文只保留软件交互、仿真界面和公开标准对接层面的内容。文章不包含客户信息、真实设备型号、私有字段、具体协议帧内容、具体固件文件和源代码实现细节。
天线列表	主菜单
校准确认	校准成功
设置倾角	倾角输入数值
倾角确认弹窗	倾角设置成功
天线信息顶部	天线信息底部
配置文件列表	固件更新列表
其他设置	输出电压设置
语言设置	英文主菜单
英文天线信息界面

一、现场维护功能范围

终端服务现场维护，不以研发调试台为主要使用场景。用户需要拿着设备接上线缆，通过屏幕和按键完成维护动作。

这一部分的重点是把 RETAP 协议能力变成现场可执行动作。现场人员不需要知道协议帧、命令码和连接时序，只需要从菜单里选择目标操作。

二、天线扫描算法

设备扫描是这个项目里比较重要的部分。总线上可能挂着多台设备，终端需要在不知道完整设备编号的情况下发现它们，并给它们分配可通信的短地址。

扫描过程按数字分支逐层尝试：

1. 候选列表先放入最低位的数字分支。
2. 每次取出一个候选，构造一段匹配条件发起扫描。
3. 如果收到有效响应，就把设备加入结果表，并尝试给它分配短地址。
4. 如果出现校验冲突、未知响应或地址绑定失败，说明这个分支下可能有多台设备，需要继续展开下一层。
5. 如果没有响应，这个分支直接剪掉。
6. 候选列表清空后，扫描结束。

这比完整穷举设备编号更适合资源受限的手持终端。终端根据响应结果判断当前分支下是否还有设备，只在必要分支上继续深入。扫描完成后，设备列表会直接变成菜单列表，用户选中某一项后，后续操作都围绕这个目标设备执行。

这套扫描流程也解决了一个现场工具常见问题：发现设备和控制设备不能割裂。扫描只找到编号还不够，终端还要立刻完成地址绑定、连接准备和结果缓存，主菜单才能直接进入校准、倾角、配置、固件这些动作。

三、Iuant 和 RETAP 协议对接

UMTS 基站系统里，Node B 通过 Iuant 接口管理远程电调天线。RETAP 负责承载电调天线相关的远程控制能力，例如设备发现、地址分配、连接、校准、倾角读取、倾角设置、信息读取、配置下发和固件下载。

这个项目做的是一个本地手持维护终端。它不代替基站主设备，定位是现场维护场景下的 Iuant/RETAP 关键控制工具，把标准协议调用包装成本机菜单动作。

项目里把协议处理分成两层：

业务功能只面对应用层动作。比如“设置倾角”不需要关心一帧怎么拼、校验怎么计算、接收缓存怎么清，只需要完成目标设备选择、输入值检查和结果提示。

这个分层避免了把按钮直接接到串口发送里。串口、协议帧、标准服务和 UI 动作之间有清楚分工，后续增加自检、告警读取、清除告警等能力时，可以继续复用同一套调用方式。

四、多级动态菜单

菜单系统做的不只是列出几个静态页面。它用链表或动态容器组织菜单层级，每个菜单节点只保存三类信息：显示内容、节点类型、触发动作。

这种设计带来两个好处：

• 固定功能可以在启动时创建，比如校准、倾角、信息、配置、固件和系统设置。
• 动态内容可以在进入页面前生成，比如扫描出的设备列表、存储卡里的配置文件列表、固件文件列表。

菜单控件按现场操作拆成几类：