• Frok原项目：oshwhub ESP32C3 墨水屏多功能
• 修改0402小封装，重新Layout布局，重新拉线
• 适配单面板，可以单面覆铜板一分钟制板法，蚀刻参考演示（强酸/氧化剂操作，务必看原视频安全规范）：
• • Bilibili TSINGHUAJOKING卓晴 固态双氧水制作PCB 一分钟制板法
• • Bilibili TSINGHUAJOKING卓晴 清洁盐酸用于制作PCB 一分钟制板法
• • 警示：PCB湿刻操作必须经由相关专业人员的指导下带好护目镜、手套等个人防护并且在通风橱下进行
• 本魔改版PCB工程：立创 EDA 开源工程 协作邀请

电荷泵网络生成面板高压轨

原理图为墨水屏驱动常见电荷泵：L1 10uH 与 Q1 CJ3400 形成开关节点，经 D1/D2/D3（1N5819WS）整流出 PREVGH 与 PREVGL。C2 10uF、C4 4.7uF 做输入输出储能，R1 10k 与 U1 470mΩ 参与开关侧偏置与采样路径。FPC 侧 C1、C3、C5–C12 等 1uF 电容挂在面板供电与参考网络上。

项目简述：独立端到端实现睡眠生理监测 IoT 系统，包含电池供电 BLE 感知从节点、ESP32 蓝牙网关与微弱生理信号算法。攻克微弱振动信号提取、受限 MCU 算法移植、电池功耗权衡、多 BLE 设备接入、异构传感总线接入、网络异常数据容错等问题，技术可迁移至低功耗传感类产品。

核心工作

BLE 低功耗床垫感知从节点

• 采集与前端：设计压电+压力双传感协同采集策略：压力传感器做低频在位检测触发，压电传感器做高带宽生理信号采集，在位检测按需启采，兼顾续航与采集性能；完成差分模拟前端，抑制基线与环境噪声。
• 算法自研与移植：针对床垫压电微弱振动信号（低信噪比、呼吸谐波与体动干扰和目标频带重叠），自研心率 / 呼吸估计算法，设计自适应滤波与运动干扰抑制链路，以置信度输出抑制体动误报；算法流式化移植至资源受限 MCU，通过增量求和与单调队列维护滑动窗口极值，将每样本开销从 O (窗口长度) 降至常数级，1 秒窗口处理实测 230ms，较初版实现提升约 12 倍；配套自建低代码拖拽式算法仿真平台（signal-analysis-lab），完成仿真 - 实机一致性验证。
• 功耗调度：基于差分闹钟实现功耗调度状态机（采样 / 同步 / 休眠），按最近任务截止时间动态计算唤醒间隔，采样窗口外对模拟前端独立断电，整机休眠功耗低至 7μA。
• 数据流水线：搭建 ADC 采样 FIFO→流式处理→结果 / 波形双队列（独立时间戳，波形 LTTB 降采样）采集流水线。
• 可靠性：实现低电量锁死保护与 FIFO 高水位紧急同步，防止数据积压丢失；支持 BLE 远程配置热更新。

ESP32 蓝牙网关

• 异构传感接入架构：设计统一传感器驱动抽象层，定义统一设备接口，屏蔽 Modbus RTU、I²C、自定义 UART、GPIO 中断等多类总线差异；采用设备表注册机制，新增传感器仅需实现接口并注册，轮询框架零改动；驱动统一输出键值对契约，映射表驱动解析，新增传感器零硬编码；单线程轮询 + 队列解耦，统一读数结构供上层消费，完成温湿度、CO₂、CO、打鼾等多维环境数据汇聚。
• 数据链路：实现多 BLE 从机扫描、连接与数据交互；基于 MQTT QoS 1 实现可靠上报，设计 FlashDB TSDB 本地时序缓存（7天窗口）与断网补传机制，网络恢复后按时间序批量补传并逐批确认删除，保障数据零丢失。
• 交互层：面向用户提供 APP 完成配网与数据查看；网关提供可被 APP 嵌套的本地调试后台，用于图表浏览与设备运维。

技术沉淀

微弱模拟信号调理降噪、生理信号算法自研与 MCU 端移植性能调优；电池 BLE 设备差分闹钟休眠唤醒功耗框架设计；异构传感总线统一抽象层与插件式扩展设计；采集流水线与波形降采样（LTTB）；BLE 多从机管理；网络异常数据缓存补发容错方案。

心率信号处理算法

传感器解耦

MQTT可靠上报与断网补传

基于 MQTT QoS 1 实现可靠数据上报，重要数据（心率/呼吸/环境）先落盘 FlashDB TSDB（7天窗口）再上报、发送成功才标记删除；波形预览仅 RAM 队列不落盘。网络恢复后按时间序批量补传并逐批确认删除，保障数据零丢失。本地完成分钟级聚合后再上报，降低上行带宽与后端存储压力。

1. 右上角用户图标 - 首选项 - 常规 - API-Fusion MCP服务器
2. MCP服务运行在 http://127.0.0.1:27182/mcp

设计参数

模型下载

实践用的PCB定位挡块模型（3MF）：PCB定位挡块.3mf

可导入 Fusion 360、Blender 等建模软件参考或直接 3D 打印。

一段 Fusion 360 Python 脚本，在草图平面生成 200×200mm 六边形蜂窝阵列：外接圆半径 5mm、壁厚 3mm，参数集中在脚本开头，改两个数即可调整孔径与密度。

下载 DXF

用法二选一：

1. 在 Fusion 360「工具 → 附加模块 → 脚本」中运行，或导入下方 DXF，用于外壳镂空、散热孔、通风面板。
2. 把脚本发给 AI，通过 Fusion MCP (右上角用户图标-首选项-常规-API-Fusion MCP服务器) 直接帮你画。

import adsk.core, adsk.fusion, math

def run(_context: str):
    app = adsk.core.Application.get()
    design = adsk.fusion.Design.cast(app.activeProduct)
    root = design.rootComponent

    # ============================================================
    # 参数配置 — 按需修改这里
    # ============================================================
    R          = 0.5   # 外接圆半径 (cm)，5mm → 改成 0.4 即 4mm
    gap        = 0.3   # 孔间壁厚 (cm)，3mm → 改成 0.2 即 2mm
    size_x     = 10.0  # 画布半宽 (cm)，10cm → 总宽 200mm
    size_y     = 10.0  # 画布半高 (cm)，10cm → 总高 200mm
    sketch_name = 'HexTile_200x200'
    # ============================================================

    apothem = R * math.sqrt(3) / 2   # 内切圆半径

    col_spacing = 2 * apothem + gap  # 列间距 (x 方向)
    row_spacing = 1.5 * R + gap      # 行间距 (y 方向)

    x_min, x_max = -size_x, size_x
    y_min, y_max = -size_y, size_y

    margin_x = apothem + gap / 2
    margin_y = R + gap / 2

    # 在 XY 平面新建草图
    sketch = root.sketches.add(root.xYConstructionPlane)
    sketch.name = sketch_name
    lines = sketch.sketchCurves.sketchLines

    # 外框 200×200mm
    corners = [
        adsk.core.Point3D.create(x_min, y_min, 0),
        adsk.core.Point3D.create(x_max, y_min, 0),
        adsk.core.Point3D.create(x_max, y_max, 0),
        adsk.core.Point3D.create(x_min, y_max, 0),
    ]
    for i in range(4):
        lines.addByTwoPoints(corners[i], corners[(i + 1) % 4])

    # 六边形蜂窝填充（flat-top，奇数行偏移半列）
    count = 0
    row = 0
    cy = y_min + margin_y
    while cy + R <= y_max - gap / 2:
        offset_x = col_spacing / 2 if (row % 2 == 1) else 0.0
        cx = x_min + margin_x + offset_x
        while cx + apothem <= x_max - gap / 2:
            pts = []
            for k in range(6):
                angle = math.radians(30 + 60 * k)  # flat-top 方向
                pts.append(adsk.core.Point3D.create(
                    cx + R * math.cos(angle),
                    cy + R * math.sin(angle),
                    0
                ))
            for k in range(6):
                lines.addByTwoPoints(pts[k], pts[(k + 1) % 6])
            count += 1
            cx += col_spacing
        cy += row_spacing
        row += 1

    print(f'Done: {count} hexagons')
    print(f'R={R*10:.1f}mm  gap={gap*10:.1f}mm  '
          f'col={col_spacing*10:.2f}mm  row={row_spacing*10:.2f}mm')
    app.activeViewport.fit()

本文用于验证博客系统新功能：Markdown 用图片语法引用 .mmd 文件，浏览器端动态加载 mermaid 渲染为 SVG。

外部文件引用

下面的图来自同目录的 渲染流程.mmd 文件，写法是 ![渲染流程](./渲染流程.mmd)：

内联 mermaid 代码块

同一个渲染函数同时支持直接写在文章里的 mermaid 代码块：

sequenceDiagram
    participant M as Markdown
    participant B as 构建脚本
    participant V as ArticleModal
    M->>B: ![图](./xxx.mmd)
    B->>B: 复制资源 + 重写路径
    V->>V: 发现 .mmd 引用
    V->>V: 动态 import mermaid
    V->>M: 渲染 SVG 替换占位

故意写错的图表

下面的图表语法错误，应显示错误提示而不影响其他内容：

flowchart TD
    A[缺少连线对象 ->

组成：一条 DataChannel 加两次手动信令

WebRTC 数据透传只需要三样东西：两端各一个 RTCPeerConnection、一条 DataChannel、一次 ICE 打洞。DataChannel 可以理解为一条点对点的双向字节管道，用法接近 TCP socket；一条连接上还能随时开很多条通道，各自独立，开新通道不需要重新走信令。

信令（交换连接参数的 SDP）不经过服务器，两端各打印一行 token，人工复制粘贴给对方。本文用纯 JS 实现的 werift 库，npm install werift 即装，无原生编译依赖。

完整脚本见附件 peer.min.js，全文 70 行。

信令交换与数据回传时序

人工搬运只有两次：A 的 offer token 交给 B，B 的 answer token 交回 A。连接建立后 DataChannel 全双工，任意一方发送，接收端原样回传一份副本。

分步最小实现

① 两端各建一个对等端

import { RTCPeerConnection } from "werift";
const pc = new RTCPeerConnection({
  iceServers: [{ urls: "stun:stun.l.google.com:19302" }], // 公共 STUN 打洞
});

② A：建通道，生成 offer，打印 token

// "chat" 只是给这条通道起的名字（对端能读到，用来区分通道用途），不做寻址
const dc = pc.createDataChannel("chat");
// 这行必须写在 createOffer 之前：werift 生成 offer 时如果一条通道都没有，
// 就不会启动 ICE gather，SDP 里连候选地址都没有，对端拿到的是废 token
await pc.setLocalDescription(await pc.createOffer());
// 返回时 ICE 候选收集（gathering）已完成，SDP 自带全部候选，之后无需再交换候选
console.log(encode(pc.localDescription)); // 一行 base64url，人工粘给 B

③ B：收 offer，回 answer，打印 token

await pc.setRemoteDescription(decode(await ask("offer token: ")));
await pc.setLocalDescription(await pc.createAnswer());
console.log(encode(pc.localDescription)); // 一行 base64url，人工粘回 A
// 对端通道打开时的接收处理 pc.ondatachannel 见步⑤

④ A：粘贴 answer token，连接自动建立

await pc.setRemoteDescription(decode(await ask("answer token: ")));
// ICE / DTLS / SCTP 自动完成，DataChannel 变为 open

⑤ 收发与 loop back

B 侧从头到尾没有调用过 createDataChannel。A 建的通道会在 B 侧通过 ondatachannel 事件自动送进来，拿到它才能收发：

// B 侧：收到即原样回传。双方都回传会无限乒乓，所以只让一侧回传
function loopBack(channel) {
  channel.onMessage.subscribe((msg) => channel.send(msg));
}
pc.ondatachannel = (event) => {
  loopBack(event.channel);
};

// A 侧：打印对端回传的内容（A 自己建的通道直接用 dc 变量收发）
dc.onMessage.subscribe((msg) => console.log("[echo]", msg));
rl.on("line", (line) => {
  if (dc && dc.readyState === "open") dc.send(line);
});

token 的编解码各只有一行：

const encode = (d) =>
  Buffer.from(JSON.stringify({ type: d.type, sdp: d.sdp }), "utf8").toString("base64url");
const decode = (line) =>
  JSON.parse(Buffer.from(line.trim(), "base64url").toString("utf8"));

运行方式

node peer.min.js answer   # 终端 B：粘 offer token，打出 answer token
node peer.min.js offer    # 终端 A：粘 answer token，然后直接打字

两端打印 连接状态: connected 后，任意一侧输入文本回车，对端收到并原样回传。

werift 有两个专属的坑，脚本注释里有标注：setLocalDescription 的返回值里 sdp 为空，必须用 pc.localDescription；SessionDescription.type 是原型 getter，序列化 token 时必须显式取 {type, sdp}，否则 answer 侧推断类型，DataChannel 建立不可靠。

下面嵌入一个纯前端的 YUV 颜色空间小实验：页面把图片从 RGB 变换到 YUV（BT.601），每个像素拆成 Y 亮度、U/V 两个色度分量，各占 8bit。你可以逐位开关 3×8 共 24 个 bit 掩码，被关闭的位直接置零，等价于把该分量量化到更少的级数；页面随即重建压缩后图像，与原图并排对比，并给出压缩率、压缩前后大小、节省空间和 PSNR 画质评分。由于人眼对亮度敏感、对色度不敏感，优先砍 U/V 的低位往往看不出差别，却能省下大量存储空间。默认的 Y6/U4/V4 档把每像素 24bit 压到 14bit，实测节省约 42% 空间。页面内置一张默认图片（base64 内嵌），也可以拖入任意本地图片，全部计算在浏览器本地完成，不上传任何数据。

用了十来年的卡西欧计算器方向键↓用不了，拆开维修

①是无法使用的按键，红色和蓝色是按键对应的扫描矩阵走线，其中红色线路通过过孔②去正面，蓝色线路通过过孔序号③来带有芯片的正面；

• 使用低功耗分析仪发现，开机电流是30μA，任意按键按下后电流是50μA，按键电流大约20μA；
• 排查红色支路上的其他按键，按下后有20μA电流增量；
• 排查蓝色支路上的其他按键，发现按下后没有任何电流增量，并且对应的按键无反应，这说明有问题在蓝色支路上，进一步检查正面序号③的过孔。

现在来到电路板带芯片的正面，过孔③在丝印P134处，它被连接到序号④K17测试点，接着通过序号⑤有绿油覆盖的走线来到序号⑥的过孔重新回到背面。

经过测量发现序过孔④到序号⑥不通，刮开 ⑤ 处的绿油，覆铜在绿油下方已经断开。外观完全看不出来：绿油完好，铜箔的裂纹藏在下面，推测是按键按压、潮气腐蚀，细铜箔出现微裂纹。飞线处理。

飞线后 ↓ 键恢复正常，通过内置隐藏的按键测试程序

带大家看看 RIGOL DM3058E 万用表的内部电路板。

同一块测试板，几根信号线本体都是悬空的——这只为了把耦合量测干净，不是产品真实接法。只在连接器上多插一根远端不接的 FPC，把悬空导体拉长后，相邻测点上的 20 kHz 方波串扰就抬到原来的 3 倍以上。中间隔接地线的测点幅度仍低一截，隔 NC 占位线的测点最脏。

测试条件

• 干扰注入：5 Vpp、20 kHz 方波（唯一有源激励）
• 观测：示波器看各测点串扰 Vpp；A / NC / B 均为悬空高阻节点
• 对比：裸板 vs 再接一根远端悬空的 FPC
• 线序上→下：测试点 A / NC 占位 / 干扰注入 / GND（接地隔离） / 测试点 B

串扰对比

测点	裸板	接悬空 FPC	变化
A（隔 NC）			50.5 mV → 167 mV（3.3×，+10.4 dB）
NC 占位			63.3 mV → 275 mV（表观 4.3×，读数含振铃）
干扰注入			激励源无变化
GND			-
B（隔 GND）			21.1 mV → 67.7 mV（3.2×，+10.1 dB）

接上 FPC 后，几个敏感测点串扰都抬到 3 倍以上，注入源本身没变。相邻引脚寄生电容粗测：裸板约 5 pF，接 FPC 后约 10 pF。

各测点本来都悬空；NC 占位点接上 FPC 后振铃更明显，示波器 Vpp 把过冲一并计入，所以 275 mV 偏高；即便按折算，涨幅仍然明显。

简要判断

20 kHz 下波长约 15 km，FPC 远小于波长，耦合走的是近场容性路径，天线辐射可忽略。悬空 FPC 等于把并行导体拉长，互容变大，受害线分到的干扰跟着变大。

A 与源之间隔的是 NC 线，B 与源之间隔的是 GND 线，间距一样。A/B 在裸板和接 FPC 后都在 2.4 倍上下：中间导体接地，大约带来 7.7 dB 隔离收益。浮置 NC 既挡不住耦合，还会被方波边沿激出振铃。

测低功耗器件电流时，开路电流档接近 0，短接表笔也应接近 0。实测短接后仍有微安级残余，手温或打火机加热单侧笔尖会让读数更大，确认干扰来自表笔热电势。

现象

仪器：RIGOL DM3058E，5½ 位台式万用表，直流电流档。

开路时电流档为 0。先碰到过红色表笔笔尖，再去短接测量，读数莫名其妙停在两三个微安，没有回零：

红色表笔电流端子与表笔尖的插入端对调

同一只红色表笔，把电流端子与表笔尖分别改接到电流档的正、负端子。

红色表笔的电流端子接正电流端子，红色表笔它自己插入负端子，短接后读数为 +6.825 µA：

红色表笔的电流端子接负电流端子，红色表笔插入正端子，短接后读数变为 −1.270 µA：

端子对调后，残余电流符号相反。

打火机加热表笔

用打火机分别加热红色表笔与另一只表笔的笔尖，再短接读数：

加热红色表笔	加热黑色表笔
加热后短接：+40.592 µA	加热后短接：−107.194 µA

单侧笔尖被加热，短接回路里出现几十到上百微安；加热不同侧，读数符号也不同。

加热实验过程：

放置一段时间后，两只表笔温度接近，再短接读数降到 0.135 µA：

热电势来源

热电势并不要求两只笔尖基材一定不同。回路里凡是异种金属结点，笔尖镀膜与基材、镀层磨损处、接插件与香蕉头、氧化膜两侧，只要结点两侧存在温差，就会按塞贝克效应产生热电势。手温、打火机火焰都在制造局部温度差；电流档把热电势驱动的电流一并读出。手碰过笔尖后，汗液还可能在镀膜与氧化层之间形成微弱原电池，再叠上一点直流分量。

表笔插入极性决定热电势在电流表里呈现正号还是负号。哪一侧更热，热电势方向就跟着变。温度差消失后，读数回到零点附近的残余值（本次约 0.135 µA）。

热电势也出现在仪器内部。开机时间一长，机内功率器件、电源与外壳之间会形成温差，输入回路和开关接点上的异种金属接头同样按塞贝克效应产生毫伏级以下的寄生电势。这部分零点残余在预热过程中会缓慢变化，只能靠预热稳定、扣零或相对测量压下去，消不掉。

ADC 通道 1～4 全是悬空，没有接传感器。板载 10 kHz 测试方波却出现在波形上；把红端子从 ADC 引脚拔掉后，四路又一起变平。这组对照把干扰源指向外部线缆的寄生电容，并排除了板内串扰作为主要来源。

步骤一：接线实物

测试板输出 10 kHz 方波，业务采集侧用 ADC Stream Scope 同时看 ADC 通道 1～4 四路。四路 ADC 引脚都悬空。测试线一端是黑、红两个香蕉端子，另一端线芯外露、什么也没接。

测试工程：github.com/createskyblue/STM32L496_ADC_DMA_MuChannel_Sample

• 黑端子 → 板上 10 kHz 测试信号
• 红端子 → 业务 ADC1（悬空引脚）
• 线缆远端悬空

步骤二：耦合波形

红端子接到悬空的通道 1 后，通道 1 出现与测试信号同频的方波，游标处约 2.733 V，幅度接近满量程。悬空引脚本身不产生信号，作为高阻抗节点却容易通过寄生路径拾取外部信号；这里的方波来自黑端子上的 10 kHz 经线缆寄生电容耦合。通道 2～4 同样悬空，也在波形上露出同相位的残余小波。

通道 2～4 上的小波，是单 ADC 规则组切换留下的。MCU 里通常只有一个 ADC，按通道 1→2→3→4 分时采样。通道 1 被耦合方波充到对应电平后，切到后面几个悬空通道，内部采样电容还带着上一通道的残余电荷，转换结果里就留下同相位的小波形。越靠后，残余幅度越小。悬空通道上的小波，是电荷被带到下一通道的结果，并非它们也直接吃到了方波。

步骤三：断开对照接线

只改一处：红端子从 ADC 引脚拔掉，黑端子仍接 10 kHz，线缆其余接法不变。

步骤四：断开后波形

四路同时变平，游标附近都在 0.503 V 附近，视窗统计几乎没有起伏。

线缆寄生电容路径

通道 1 上的方波从线缆进来：四路 ADC 引脚都悬空。两根导线并行走线时存在寄生电容，黑端子上的 10 kHz 方波经这层电容送进红端子连接的悬空通道 1。万用表粗测线间电容约 0.389 nF，量级与寄生耦合相符。红端子一拔，耦合路径断开，四路一起归平。

结论

经对照，四路悬空 ADC 上的 10 kHz 方波属实，板内串扰并非主要来源。原因分两层：外层是测试线缆两根导线之间的寄生电容，把黑端子上的方波送进了红端子连接的悬空通道 1；内层是单 ADC 规则组分时切换，后续悬空通道因采样电容残余电荷留下同相位小波。

验证方式是断开红端子后波形归平。后续用这根线做信号注入时，应把远端悬空、通道间距和走线长度当作可控变量；板级排查若只见业务通道异常，先断外部引线再查 PCB 走线，可以把板内串扰和线缆耦合分开。

概要

普冉 PY32（兼容 STM32F0 系列的国产 MCU）驱动一颗外部采样芯片，SPI 引脚配成 AF 复用，CS 由软件 GPIO 控制。同一组物理线路，软件 SPI 正常，硬件 SPI 发 1 字节时 SCK 出了 9 个脉冲（预期 8），多出的脉冲出现在数据之前，从设备数据整体错位。断点定位到 PY32 厂商 HAL 的 HAL_SPI_Transmit：它在每次传输开始前先把 SPE 清零再重新使能，关闭 SPI 这段时间 SCK 失去主动驱动，被外部周期干扰扰动出一个异常边沿。屏蔽掉这句 Disable 之后异常脉冲消失，从设备恢复正常。

因果链：

问题是怎么来的

项目需要读一颗外部采样芯片，硬件 SPI 死活驱动不了从设备。软件 SPI 可以正常驱动，说明接线和从设备本身基本正常，也因此把排查重点转向硬件 SPI 的时序和引脚状态。

期间 GLM 5.3 Flash、GPT 5.6 Luna 和 Sol 都接了逻辑分析仪的 MCP 能自己抓波形，三个轮番试了 14 个小时没找出根因，最后人工下场。

实验：8bit 数据出了 9 个时钟

对比实验：分别用软件 SPI 和硬件 SPI 发送 1 字节、2 字节，接入逻辑分析仪抓波形。同样的线，软件 SPI 正常；硬件 SPI 发 1 字节时 SCK 出现 9 个脉冲（预期 8 个），多出的那个脉冲出现在数据之前，把整个字节流错位 1 bit：

已降速抓取，速率与后面的示波器图不一致。

上示波器看模拟波形，确认这个干扰正是多出来的那个脉冲：

根因：HAL 入口的 Disable 让 SCK 失去驱动

断点调试定位到 HAL_SPI_Transmit 函数体，Disable 就在传输开始前的配置段。源码截图里两个红框分别标出 __HAL_SPI_DISABLE(hspi) 和 __HAL_SPI_ENABLE(hspi)，问题出在两个红框之间的这段区间：

SPE 清零之后，SPI 外设不再主动驱动 SCK。对当前这颗 PY32 的 SPI/IO 实现，SCK 在该时间窗口内失去原有的主动驱动状态，实测表现为容易受到外部干扰影响。

CS 在调用 HAL_SPI_Transmit 之前就由软件拉低，整个传输期间一直有效，这个时间窗口完全落在从设备的选中期内。把断点停在 Disable 之后，程序暂停、SPI 保持关闭，此时用示波器看 SCK 引脚，能看到持续的外部周期干扰：

该干扰边沿落入 CS 有效期间，最终表现为从设备多接收了一个时钟，后续数据整体错位 1 bit。

缓解尝试

CPOL=0 时 SCK 空闲电平是低，按空闲电平给 SCK 加下拉，想把 Disable 期间失去主动驱动的引脚钉在低电平。效果不好，干扰仍在：

实际测试中，弱下拉仍无法消除落在输入阈值附近的毛刺。

最终修复

把 HAL_SPI_Transmit 入口的 __HAL_SPI_DISABLE(hspi); 屏蔽掉：

/* 厂商 HAL 的 HAL_SPI_Transmit()，传输开始前的配置段 */

/* 屏蔽这句 Disable，让 SPE 保持常开 */
/* __HAL_SPI_DISABLE(hspi); */

/* ... 写 CR1 / CR2 配置 ... */

if (((hspi)->Instance->CR1 & SPI_CR1_SPE) != SPI_CR1_SPE)
{
  __HAL_SPI_ENABLE(hspi);
}

屏蔽之后，在当前 HAL 的这条传输路径中 SPI 保持使能状态，原先位于 Disable 和 Enable 之间的窗口被消除；后面那句条件使能因为 CR1 & SPI_CR1_SPE 已经等于 SPI_CR1_SPE 也不再触发。SCK 始终由 MCU 强驱动，实验中观察到的异常边沿消失，多余的脉冲消失，从设备恢复正常。

同类问题

这个现象并不是 PY32 独有。ST 社区也有过类似案例：SPI 被关闭期间 SCK 出现异常跳变，最终导致从设备多收到一个 bit。ST 官方回帖给的解法是置 AFCNTR（Master Keep IO State）。

Linux 侧也有人提过同一件事。Ben Wolsieffer 提交给 spi-stm32 驱动的补丁（spi: stm32: enable controller before asserting CS，邮件列表存档）说明里写得很直白：STM32F4/F7 的 MOSI 和 CLK 在控制器禁用期间会浮空，而 CS 是普通 GPIO、一直被驱动，于是存在一段 CS 已选中、SPI 引脚却没人驱动的窗口，杂散信号可能扰乱通信。同一份说明还提到 STM32H7 没这个现象，因为驱动置了 AFCNTR。

一些补充

一些较新的 STM32 SPI 外设提供 AFCNTR 或类似的 IO 保持机制，用于在 SPI 禁用期间继续控制相关 AF 引脚，具体寄存器和行为以对应型号的参考手册为准。本文这颗 PY32 没有这个机制，只能软件规避：改 HAL 保持 SPE 常开，或者 Disable 期间用同组 GPIO 接管 SCK 电平。

这不算"HAL 有 Bug"，更准确的说法是 HAL 的 Disable → Enable 流程触发了 SPI 外设在 Disable 状态下的 IO 行为问题。结论只针对 PY32 及其 HAL 实现。

工程经验

SPI 速率要求不高时我更倾向软件 SPI。硬件 SPI 的优势是性能、CPU 占用和 DMA，软件 SPI 的优势是可控性：CS、SCK、MOSI 的电平和时序都由代码直接控制，不依赖 SPI 外设自身的状态机以及对应 HAL 对外设状态的处理。MCU 还可能因为成本、供应链、国产替代被换掉，换一颗就要重新踩一遍外设差异的坑。

声明： 本文是网上看到 B站视频《空调开发踩坑实录：东北外机 WiFi 集体失联》后整理的分享笔记，原始链接：https://www.bilibili.com/video/BV1Ch816CEhR。本文作者不是该视频的作者，未参与其中的开发和测试。 文中工程细节均来自该视频内容。

故障现象

东北冬季，一批空调外机的 WiFi 模块集体失联，常温复测却全部正常。用高低温箱逐档降温复现：常温 25°C 连接稳定、吞吐全达标；降到 0°C 连接速率下降、偶发丢包；到 -15°C 时近三分之一的样机直接断联。环境温度回到常温后，故障全部消失，确认失效与低温强相关。

低温复现画面取自原视频（视频链接）。

原因：晶振低温失效，来料以次充好

WiFi 模块的射频载波由晶振提供基准频率。这批射频晶振来自居民楼小作坊，回收旧物料以次充好，温度特性达不到标称规格：低温下频率漂移超出射频电路的容许范围，模块直接用不了。常温测试全程绿灯，问题只在低温现场暴露。

教训：高低温循环测试

以次充好的物料在常温下测不出来。产品出厂前做高低温循环测试，把这类器件挡在研发阶段；零下二十度的客户现场不该是物料的第一次低温测试环境。

嘉立创实战派 S3 做的语音输入板：麦克风拾音，转文字喂给 AI 助手，平时挂一个快充头供电。用了几天，屏幕黑了，插电脑没反应。

快充头误升档打穿入口 DC-DC，连带伤了音频芯片。换两颗芯片，恢复正常。

语音输入	设置	触控板

原因：快充头误升高压

板子对外只有一个 Type-C，直连 ESP32-S3 USB 引脚，中间没有隔离；供电侧先进 DC-DC 降压再喂给 ESP32-S3。

快充头默认输出 5V，靠 CC 线协议握手后才升到 9V/20V。线缆接触不良或 CC 识别抖动时，快充头可能误判握手完成、直接放出高压档，入口那颗 DC-DC 直接承受过压，击穿后主供电断，整板没电。

排查：限流上电 + 热成像定位

坏板不能直接满压上电。飞线接外部可调电源，先 5V / 50mA 试探：ESP32-S3 未启动，电源进入恒流（CC）状态，后级低阻短路。

切到 1V / 1A，电压低、电流足，故障点发热。用自制热成像工具扫描，发热点集中在序号 1、序号 2，两颗同型号 DC-DC：一颗供 ESP32，一颗供音频。高压从 Type-C 进来，首当其冲是入口那颗（序号 1）。

绕过 DC-DC，先启动系统

飞线绕过坏 DC-DC，外部直接给 3.3V；先不插屏幕，最小系统启动，避免外设干扰判断。

二次故障：I²C 扫不到录音芯片

接串口看日志，程序没跑起来：I²C 总线上扫不到音频 ADC。这颗芯片热成像只有 50 多度、微烫，但它挂在同一条被高压打过的供电链路上，判定连带损坏（序号 3，板子背面）。

修复

DC-DC 和音频芯片各换一颗。

• DC-DC 换掉：5V 短路消失，主供电恢复，屏幕点亮。
• 音频芯片换掉：I²C 识别正常，录音恢复。

排查方法小结

1. 故障板先限流上电（5V/50mA），确认有无短路，不满压复现。
2. 电源进 CC 恒流 = 短路，切低压大电流（1V/1A）让故障点发热，热成像定位。
3. 飞线绕过疑似故障点、最小化系统，先把能跑的部分跑起来，再看串口日志找二次损伤。
4. 同一条高压/电源链路上的芯片，热成像不烫也要怀疑，串口日志比温度更早报故障。

10 位正弦波表把一周期正弦量化为 0..1023，每位权重不同：高位定量程，低位定分辨率。屏蔽某位等于该位 stuck-at-0。屏蔽低位只让量化步长变粗、波形变糙；屏蔽高位使上半个周期被镜像折回下半区，形成一串折叠拱形、表观频率翻倍，即 foldover 失真。下方 Demo 可勾选 10 个位、切换周期数、自适应 Y 轴，对比原始与屏蔽后波形。

打开交互 Demo

这块 NH50BAT-4 笔记本电池闲置约两个月后，电脑显示电量 0%，接上充电器也充不进去。拆包逐节测量，其中一颗电芯是 0 V。

电芯坏掉只是其中一层，保护板有没有跟着锁死才决定这个包还值不值得修。下面按实际排查顺序记录：从电池接口飞线接 STM32L496 读 BQ40Z50，尝试解锁，最后按解锁结果和电芯成本决定换芯还是买整包。

闲置后的电池包故障现象

开机后电量一直显示 0%，插充电器也没有反应。拆包逐节测量，其中一颗电芯 0 V；单独拆出来再量还是 0 V，用可调电源设 2.7 V、200 mA 试着激活，没有充电电流，这颗按失效处理。

电芯失效之外还有一层要单独验证：保护板有没有因为故障或保护状态拒绝工作。这就是后面要直接读 BQ40Z50 的原因。

超声波焊接与四颗电芯更换边界

这个电池包的外壳使用了超声波焊接，无法像螺丝固定的外壳那样无损打开。要看到内部电池和保护板，需要先对外壳进行破坏性拆解，再重新处理外壳的固定和密封。

四串电池包也不适合只换一颗。新电芯和剩下三颗旧电芯的容量、内阻、电压状态都不一样，混装会带来不均衡风险，正式更换必须四颗一起换，装配前查一致性。后面为了先验证保护板，我只临时换了一颗，这组混装电芯不能当成能正常充放电的成品，全程没有对它充电或大电流放电。

保护板上的 BQ40Z50 电池管理芯片

保护板上的主控是 BQ40Z50，负责采集电芯信息、保存电池状态，并参与充放电保护控制。电脑显示 0% 又充不进电，光看电芯电压判断不了保护板还能不能工作，所以得直接读这颗芯片。

电池接口飞线接入 STM32L496

不用焊 BQ40Z50 的引脚，直接从电池接口飞线到 STM32L496，就能通过 SMBus/I²C 访问保护板。电源、地和通信线按接口丝印和实物走线确认。

I²C 地址扫描与电池数据读取

先做地址扫描确认保护板在线，扫到 BQ40Z50 的标准 7 位地址 0x0B，接着读标准电池数据，串口输出如下：

Manufacturer: SMP-LGC-2750
Device: C41
Chemistry: LION
Pack Voltage: 13247 mV
Relative SOC: 0 %

四节电芯的读数：

Cell1: 3025 mV
Cell2: 3435 mV
Cell3: 3802 mV
Cell4: 2986 mV
Cell Sum: 13248 mV
Pack Voltage Difference: -1 mV

四节之和与总压只差 1 mV，采样和通信链路是可信的。816 mV 的最大压差来自刚换上的那颗新电芯和三颗旧电芯混装，不代表四颗新电芯配组后的结果。

BQ40Z50 状态读取结果

能读通不代表允许充放电，状态寄存器才是关键：

SafetyStatus:    0x00000000
PFStatus:        0x00000801
OperationStatus: 0x00007381
SEC:             3
XCHG:            SET

SEC=3 是 Sealed 状态，PFStatus 置了故障位，XCHG 表示充电被禁。芯片在线和电池不能用，这两件事同时成立。

常见 Unseal Key 的发送结果

先试 BQ40Z50 常见的两组默认 Unseal Key：

0x0414
0x3672

按 ManufacturerBlockAccess 0x44 编码后发出去：

[44 02 14 04]
[44 02 72 36]

发完回读 OperationStatus，没有变化：

Post-unseal OperationStatus: 0x00007381, SEC=3
Unseal result: still Sealed (SEC=3); key pair was not accepted

两组 key 都没被接受，说明这块的量产配置换过密钥。没有正确的 key，标准解锁流程走不下去，这也证明不了芯片本身坏了。

暴力搜 key 这条路走不通

两组 16 位 key 合起来是约 2^32（42.9 亿）种组合。只按两次 4 字节写入加地址应答的理想传输时间算，100 kHz 传完一轮是 45 天量级，1 MHz 也要 4.5 天，还没算芯片处理时间、状态回读和失败等待；我当前程序在两组 key 之间留了 10 ms 间隔，按这个节奏是 1.4 年往上。何况芯片一般会限制连续失败次数，搜到一半就会停。

所以提 I²C 频率没有意义，要么拿到这块电池对应的 Unseal Key，要么换一块已经配置好的保护板。

换芯还是买整包

继续修要同时处理三件事：四颗电芯重新采购、保护板已经记了 PF、BQ40Z50 还锁在 Sealed。

四颗 3400 mAh 电芯单价 16.5 元，合计 66 元；同型号完整电池包 77 元。材料价差只有 11 元，芯片、焊接、时间和解锁工具的钱都还没算进去。解锁已经失败，再买保护板芯片也没有明确收益，总成本很容易接近或超过整包。

结论

这块电池包的问题定位到两层：一颗电芯 0 V 失效，2.7 V/200 mA 外部激活没有充电电流；保护板侧 BQ40Z50 能通信，但处于 Sealed 且记了 PF，常见 Unseal Key 无效。芯片是好的还是坏的没法下结论，只能说标准解锁流程走不通。

材料上四颗电芯 66 元对整包 77 元，加上解锁失败和 PF 未清除，继续修不划算，最后买了完整电池包。

调试代码与实测工程

本次 STM32L496 诊断代码位于公开仓库：STM32L496_BQ40Z50_DIAG。

相关文件包括：

• Core/Src/bq40z50_diag.c：地址扫描、标准电池数据、单节电压和 BQ40Z50 状态读取。
• Core/Src/bq40z50_protocol.c：Unseal 数据帧编码和 SEC 字段解析。
• Core/Src/i2c.c：STM32L496 的 I²C1 初始化。
• tests/test_bq40z50_protocol.c：验证 key 字节顺序和数据帧格式。

我想为台风厂商的一款手环制作自己的表盘。按平台的流程，想制作表盘需要先申请入驻；入驻要求提供 5 个原创设计，每个设计配一张图片和一个视频。入驻后才能拿到开发者工具，未入驻就无法继续设计表盘、制作文件并安装到自己的手环上。由于只想做一个表盘，不打算为凑数量再补做 4 个设计，最终审核未通过。现在先把这两个 HTML demo 放在博客里自娱自乐。

这个 HTML 页面在绿色点阵手环表盘中加入黄色 14×14 表情区，同时显示当前日期、时间和星期。页面直接在浏览器中运行，表情序列按固定节奏遍历切换，时间字段跟随系统时钟。

我想为台风厂商的一款手环制作自己的表盘。按平台的流程，想制作表盘需要先申请入驻；入驻要求提供 5 个原创设计，每个设计配一张图片和一个视频。入驻后才能拿到开发者工具，未入驻就无法继续设计表盘、制作文件并安装到自己的手环上。由于只想做一个表盘，不打算为凑数量再补做 4 个设计，最终审核未通过。现在先把这两个 HTML demo 放在博客里自娱自乐。

这个 HTML 页面把三行点阵数码管、星期指示、心形图标和心率读数组合成一个手环表盘展示。页面直接在浏览器中运行，时间、日期和星期跟随系统时钟更新，心率用于前端演示展示随机值。

项目仓库：github.com/RT-Thread/rt-thread（实时操作系统及设备驱动项目）

串口 DMA 接收只有一个核心取舍：接收缓冲是否直接承担 FIFO 职责。RT-Thread 的两代驱动给出了两种答案。

经典驱动的 DMA 缓冲即 FIFO

经典驱动把 DMA 缓冲区直接当作串口环形队列使用。DMA 写入数据，应用从同一块缓冲区读取，中间没有额外拷贝。

缓冲区写满后，DMA 继续前进并覆盖旧数据。这套方案不追求保存全部历史数据，优先保证接收路径持续运行。

它的哲学很直接：用最少的内存和最短的数据路径换取性能，溢出时接受旧数据损失。

V2 驱动的 DMA 缓冲与 FIFO 分离

V2 驱动使用一块连续的循环 DMA 缓冲区。HT 表示前半区写完，TC 表示后半区写完，软件按两个半区交替处理，形成软件意义上的 ping-pong；DMA 控制器配置的仍是一块连续内存。

处理完成的数据再交给下方的应用 FIFO。DMA 接收和应用读取各自拥有缓冲边界，应用 FIFO 可以选择丢弃新数据或覆盖旧数据。

它的哲学是把接收动作和数据管理分开，用额外内存和一次搬运换取更清晰的边界与恢复方式。

取舍

两种方案都无法让有限缓冲区承受无限输入。差别是资源优先级：

• 资源紧张、输入可控、允许覆盖旧数据：DMA 缓冲即 FIFO。
• 数据完整性优先、需要明确处理溢出：连续 DMA 缓冲与应用 FIFO 分离。

RT-Thread 的实现说明，串口 DMA 的关键决策是明确溢出发生时由系统保留什么、放弃什么，再选择 DMA 直写 FIFO 或连续 DMA 缓冲加软件 FIFO。

一句话：同一行的扫描线先缓存，连续线段合并后再写入屏幕。

U8g2 绘制一个中文字符时，会把字形拆成很多水平线段。旧的写法每得到一段就操作一次 TFT，新的写法先把同一行的连续线段放进 lineBuf，等这一行结束后通过 DMA 一次写入。

U8g2 在这里运行于彩色 TFT 屏幕，像素数据需要携带颜色信息，单次写屏代价更高。这个设备只有 8KB 内存，无法直接放入 LVGL 这类完整 GUI 框架，只能保留 U8g2 的字形解码和自己的显示适配层。

菜单文字数量较多，逐个取模后展开成未压缩点阵会快速消耗 Flash。Flash 空间同样有限，所以字形数据需要保持压缩形式，由 U8g2 在绘制时解码成水平扫描线。后面的优化只处理这些扫描线如何写入 TFT，保留压缩字库和现有文字显示能力。

两种写法的区别

旧路径反复执行：

水平线段 -> 设置 TFT 窗口 -> DMA 写入 -> 等待完成

新路径变成：

水平线段 -> lineBuf -> 设置一次窗口 -> DMA 批量写入

两种算法写出的像素相同，区别是屏幕提交次数。Demo 把中文字符“中”放到两块 32×16 屏幕上，左侧逐段提交，右侧缓存后提交。

缓存提交的触发点

DisplayAdapter_drawFastHLine() 记录上一段的行号和结束横坐标：

• 同一行，起点等于上一段终点：继续写入缓存；
• 换行或出现间隔：提交上一批缓存；
• 文字绘制结束：用零长度调用主动提交最后一批。

项目中的提交调用是：

DisplayAdapter_drawFastHLine(888, 888, 0, 0xFFFF);

这里的 len 是 0，不会真的绘制像素。888,888 只负责制造一次坐标边界，让缓存中的数据进入 TFT。

适用范围

这项优化只改变水平线段的写屏方式，不改变 U8g2 的 UTF-8 解码和字形查找。中文、英文、数字只要经过 DisplayAdapter_drawFastHLine()，都可以使用同一套缓存逻辑。

当前效果已通过交互 Demo 展示。项目没有记录独立的帧率或耗时数据，因此这里只说明写屏提交次数减少，不给出虚构的加速比例。

这套物联网遥测系统跑在一台淘汰的旧安卓手机上（8 核 ARM，5.7GB 内存，Termux 当 Linux 服务器）：设备通过 MQTT 上报温度、湿度、电量，Go 后端订阅解析后写入 SQLite，网页面板实时显示速率曲线、在线设备和电量状态。最新一轮压测用 4000 台模拟设备持续上报，平均每秒处理 1.95 万条，60 秒窗口峰值 2.03 万条；同一套程序原样搬到 4 核 x86 云服务器，峰值 7.1 万条/秒，200 万条零丢失。

• 全链路：设备接入、数据解析、落库、网页监控面板与压测工具，同一套 Go 源码
• 吞吐：旧手机平均 1.95 万条/秒；4 核 x86 峰值 7.1 万条/秒；1 万台设备并发建连全部成功，平均连接耗时 191.5ms
• 稳定性：收到退出信号后先停止接收，再排空队列落库，最后退出，实测积压 49.6 万条零丢失
• 性能定位：用 pprof 做 CPU 采样分析，火焰图交给 AI 解读定位热点

下面这张面板是最新一轮压测的实况：4000 台设备每台发 500 条，1 分 44 秒收到 197 万条，平均每秒 1.95 万条，数据库写入 87MB，速率曲线全程无衰减。压测端共发出 200 万条，面板收到 197 万条，差额来自投递模式：这轮用 QoS 0（发出即算完，不逐条等对方确认），设备量超过链路处理能力时，中间的消息中转站会丢掉一部分过载消息。要求一条都不能少的业务改用 QoS 1（每条等确认，速度慢一些）。文中提到的零丢失都做过条数核对。

架构设计

收消息的环节只把数据拷进缓冲队列，不做解析；解析和统计由 4 个 worker 并行处理；落库由单个 writer 攒够 1000 条后打包成一个事务写入。两级缓冲队列各 10 万容量，吸收突发流量，也给退出时留出排空时间。面板所需的总消息数、每秒速率、在线设备全部从内存读取，不查数据库，看面板不影响数据接收。

性能定位

稳态下用 Go 自带的 pprof 抓 CPU 采样，导出火焰图（横条宽度是该函数占到的采样比例，纵轴是调用栈深度），采样结果直接交给 AI 解读，几秒就能出结论。4,964 个采样点的分布是落库路径 33.4%、MQTT 消息接收 15.7%、运行时调度 13.1%、JSON 解析 12.4%，没有一处能靠换掉单个组件解决。同一时刻的系统监控：后端程序占用 2.4 个 CPU 核、内存 58MB，消息中转程序占用 0.5 个核。

服务规模

以这台手机实测的每秒 1.95 万条为基准（换成 QoS 1 稳态 1.57 万条算更保守，结论不变），一天约能处理 16.8 亿条。按常见上报频率折算：

10 万台设备的真实负载只吃掉不到 1% 的吞吐能力，30 万台也只占 0.9%（每秒 167 条）。吞吐不是瓶颈，真正的约束是连接数和存储。

连接数。常态在线的长连接模式下，每个连接占 30 到 50KB 内存，加上消息中转程序是单线程，这台手机的合理规模是 1 到 3 万台同时在线；要撑 10 万长连接就得换成多核服务器或者拆多个网关。但电池供电的设备（水表、烟感这类，休眠、唤醒、上报、立刻断开）本来不适合长连接，改走短连接后这个约束直接消失，10 万台可行。代价有两个：一是重连速率，10 万台按 15 分钟上报约 111 次/秒重连，实测建连能力约 1000 次/秒，余量 9 倍；二是必须让设备错峰唤醒（随机延迟 0 到 60 秒），否则整点会打成重连风暴。

存储。单条约 120 字节，30 万台设备每天 1.7GB、每月 52GB。压测中观察到单张表写到 200MB 以内速度不衰减，涨到 800MB 时掉到四分之一，200MB 约等于 175 万条，也就是 1,200 台设备一个月的量。按这条边界推算分表粒度：千台级别按月分表就够，10 万台约 4 小时一张表，30 万台按小时一张表（每月 720 张，每张约 72MB）。这部分是按实测边界外推的设计值，没有跑过 30 万台的真机验证。

测试环境

并发建连这一项按有据可查的数字写：压测日志完整留档的是 1 万台设备全部建连成功、平均连接耗时 191.5ms（QoS 1，每台 3 条）；更早一轮 3 万台的实验只在架构文档里有结论、没有留下日志，所以没有写进正文。

嵌入式设备要长期运行，部署后连续跑几个月是常态。内存一天漏几十字节，几周后系统卡死或看门狗复位，故障现场随重启一起丢。现场排查只能靠猜，猜不中就要返场，代价不小。可观测工具把这类问题在开发期抓出来：记录每一次内存分配与释放，退出时核对配对，谁漏了、漏在哪，一次跑完就有答案。这次用四种工具实测同一个泄漏程序，看它们各自怎么用、输出什么。

工具核对每次malloc与free

可观测的思路：让工具记录每一次 malloc 和 free，程序退出时核对配对，把未释放的块连同调用栈一起报告。趋势靠全量记录呈现，不用人眼推演。

实测程序 leak1 故意埋了两个泄漏：100 次循环里，create_packet 每次分配后忘了释放，lost_pointer 先分配一块又覆盖指针，旧块直接丢失。后面四个工具的输出都来自它。

• 下载 leak1.c：valgrind、massif、ASan 三节用的程序
• 下载 leak1_mt.c：mtrace 版，带记录开关

valgrind：未释放块与调用栈

最常用的内存检查工具，不需要改代码。直接运行：

valgrind --leak-check=full ./leak1

输出节选（真实数字）：

==16075== 51,200 bytes in 100 blocks are definitely lost in loss record 1 of 2
==16075==    at 0x488545C: malloc (vg_replace_malloc.c:446)
==16075==    by 0x108913: lost_pointer (leak1.c:15)
==16075== 107,350 bytes in 100 blocks are definitely lost in loss record 2 of 2
==16075==    at 0x488545C: malloc (vg_replace_malloc.c:446)
==16075==    by 0x1088C3: create_packet (leak1.c:7)
==16075== LEAK SUMMARY:
==16075==    definitely lost: 158,550 bytes in 200 blocks

每个泄漏点一行：字节数、块数、调用栈。definitely lost 是确定漏掉的，still reachable 是进程结束前没释放但指针还在的，这类不算 bug。by 行直接指出泄漏发生在哪个函数的哪一行。

massif：堆内存增长曲线

valgrind 自带的堆画像工具，记录运行期间堆内存随时间的变化：

valgrind --tool=massif ./leak1
ms_print massif.out

输出是一张文本版曲线图，纵轴堆内存、横轴运行时间（节选）：

    KB
161.4^                                                                    ###
     |                                                                  @@#  :
     |                                                                :@@@#  :
     |                                                             ::@:@:@@@#  :
     ...
   0 +----------------------------------------------------------------------->ki
     0                                                                   149.8
Number of snapshots: 70
Detailed snapshots: [28, 34, 40, ..., 68 (peak)]

正常程序的曲线锯齿但长期平稳，泄漏程序锯齿且整体持续上行。

只看最终数字可能漏掉缓慢增长，曲线让趋势直接可见。怀疑泄漏是每次操作漏一点的缓慢累积，先跑它看形状。

ASan：编译期插桩

地址消毒器，编译时改写代码里的内存访问，运行时检查：

gcc -fsanitize=address -g leak1.c -o leak1_asan
./leak1_asan

输出泄漏报告（节选）：

==934==ERROR: LeakSanitizer: detected memory leaks

Direct leak of 107350 byte(s) in 100 object(s) allocated from:
    #1 0x... in create_packet /home/codespace/tmp/leak.c:4
    #2 0x... in main /home/codespace/tmp/leak.c:7

Direct leak of 51200 byte(s) in 100 object(s) allocated from:
    #1 0x... in lost_pointer /home/codespace/tmp/leak.c:5

SUMMARY: AddressSanitizer: 158550 byte(s) leaked in 200 allocation(s).

格式与 valgrind 类似：泄漏字节数、块数、调用栈。额外能查数组越界、重复释放。局限是依赖运行时环境，容器等受限环境可能无法启动，实测在 proot 容器里因 shadow memory 映射冲突直接崩溃。

mtrace：glibc内置记录

glibc 自带的内存记录机制，不依赖额外工具链，适合 valgrind 装不上的嵌入式环境。先在代码里开启记录：

#include <mcheck.h>
int main(void) {
    mtrace();          /* 开始记录 */
    /* 业务代码 */
    muntrace();        /* 结束并写日志 */
    return 0;
}

编译时链接调试库，运行后生成日志：

gcc -g leak1_mt.c -o leak1_mt -lmalloc_debug
MALLOC_TRACE=mtrace.log ./leak1_mt

日志按行记录每次分配与释放（节选）：

= Start
@ ./leak1_mt:[0x984] + 0x30000224a0 0x400
@ ./leak1_mt:[0x9d4] + 0x30000228b0 0x200
@ ./leak1_mt:[0xa04] - 0x3000022ac0
= End

• 是分配，记录地址与大小；- 是释放。离线把未释放的块按调用点聚合：

  4096 bytes in   1 blocks  @ /lib/...:(_IO_file_doallocate+e8)[0x6ec88]
107350 bytes in 100 blocks  @ ./leak1_mt:[0x984]
 51200 bytes in 100 blocks  @ ./leak1_mt:[0x9d4]
TOTAL: 162646 bytes in 201 blocks

第一行是 printf 的内部缓冲，属于正常分配，剔除后与 valgrind 的数字一致。glibc 2.35 之后需要显式调用 mtrace()，不再靠环境变量自动开启。

AI执行分析，人负责设计

这些工具的输出都交给 AI 解读：让 AI 执行分析命令、读报告、把泄漏点整理成结论。人不需要逐行翻代码，知道有哪些工具、各自输出什么就够。本地开发首选 valgrind 一步到位，怀疑缓慢增长先跑 massif 看曲线，装不了工具链的环境用 mtrace。执行与分析交给 AI，人把精力留给设计。

内存生命周期的所有权设计

工具定位泄漏，正解在架构：每个动态内存分配都要有明确的所有权。谁分配，谁负责释放；所有权转移要显式交接，由新持有者负责。malloc 与 free 成对是设计结果，靠约定保证，不靠运气。

实测程序的两个泄漏点，一个忘了释放，一个覆盖指针丢了所有权，都属于所有权没有落实。工具的价值是验证所有权是否被遵守：配对漏掉一次，跑完就现形。人负责把所有权架构设计好，AI 负责跑工具，工具负责验证设计。

吞吐上不去、并发撑不住、单请求变慢，都要先定位卡在哪一步。火焰图把采样到的调用栈画成嵌套矩形：横条越宽，这个函数占 CPU 越久；越往上叠，调用栈越深。它回答的是 CPU 时间去哪了，最宽那块就是最占 CPU 的环节。这类图严格来说叫 On-CPU 火焰图，只统计真在 CPU 上跑的时间；等 IO、等锁、等网络的阻塞时间不在图上，对应有专门的 Off-CPU 火焰图来分析。

• 读法：宽度是 CPU 占比，自下而上是调用栈由浅入深
• 生成：采样后一条命令折叠出图，不改被测程序
• 前提：编译保留帧指针和函数边界，否则栈展不开

图怎么读

• 宽度是该函数占 CPU 的比例，不是执行时间，也不是调用次数。
• 纵向是调用栈深度，父函数在下，被它调用的直接叠在上面。一条竖线从上往下读，就是一条完整的调用链。
• 横向没有时间含义，同层按函数名排序，左右不代表执行先后。

递归在图上是一根逐层收窄的塔，塔的高度对应递归深度。

怎么生成

perf、Go 的 pprof、Python 的 py-spy、浏览器的 Performance 面板都能出这类图，读法通用。下面以 perf 为例。

被测程序是一段示例源码 flame_demo.c，编译时要保住栈信息，四个选项决定图能不能看：

gcc -O2 -g -fno-omit-frame-pointer -fno-inline -fno-optimize-sibling-calls -o flame_demo flame_demo.c

编译好就能采样出图，两条命令：

# 采样：99Hz，只采用户态；把 ./flame_demo 换成 -p <PID> 可附加到已运行的进程
perf record -e cycles:u -F 99 -g -o perf.data ./flame_demo
# 折叠并出图，产出的 SVG 可点击下钻、可按函数名搜索
perf script -i perf.data | stackcollapse-perf.pl | flamegraph.pl > flame.svg

采样不改被测程序，代价是统计误差，热点低于 1% 时宽度不可信。频率取 99Hz 而不是 100Hz，是为了避开与系统时钟节拍的整数倍关系，否则周期性任务会把样本全堆在同一条指令上。

出图结果如下：

四个部分各占约四分之一的 CPU，宽度接近。注意 run_all 只占 75.05%、part_fib 直接挂在 main 下，这是编译器优化留下的痕迹，下一节解释。

图上的伪影

火焰图是栈展开结果的图像，不是调用图的等价物，三处失真最常见。

尾调用。函数最后一句是调用另一个函数时，-O2 会编成 jmp 而不是 call，跳转前先销毁自己的栈帧，帧指针链里就少了这一层：被调函数直接挂到更上层的调用者下面，占比也对不上（上图的 run_all 只占 75.05% 就是这么来的）。加 -fno-optimize-sibling-calls 可还原。

内联。-O2 默认内联，被内联的函数在栈上不存在，热点并进调用者的块里。这是图上出现“一个平顶宽块”的常见原因之一——不过平顶也不全是伪影，函数自身计算量大、不怎么调用子函数时也会呈现平顶，需要结合代码判断。

栈展开截断。默认按帧指针展开，遇到不带帧指针的代码（系统库、汇编优化过的数学库）就停在那里，函数在图上表现为凭空多出的宽块。老内核的展开器还有深度限制，深递归的塔会比实际浅。换 DWARF 展开（perf record 加 --call-graph dwarf）或 LBR 可缓解。

AI 做交叉编译测试，要在主力电脑上装整套 ARM 工具链，装完处理 PATH 与库冲突，测试完再卸。跑 Web 后端 demo，又要起 Node 或解释器环境。一次测试，主力机多出一堆临时环境。旧安卓手机接住这个活：Termux 里起 Debian 容器，工具链和 Web 服务都装在容器内，测试与主力机完全隔离。

沙盒结构

• Termux：Android 上的 Linux 环境，自带 clang 与包管理器，普通应用权限即可运行
• proot-distro：容器管理工具，无 root 权限，把发行版 rootfs 挂在用户目录下运行
• Debian 容器：proot 内装 Debian（glibc），承载裸机交叉工具链与 Web 后端
• 工具链：xpack arm-none-eabi-gcc 15.2.1，解压即用，无需安装

容器选型有一个硬约束：Termux 官方仓库没有 arm-none-eabi-gcc；xpack 的 aarch64 Linux 版是 glibc 动态链接，Alpine（musl）容器运行时报缺动态链接器，Debian（glibc）容器可以正常执行。容器必须与工具链的 libc 匹配。

单片机固件交叉编译

PY32 系列固件模板（Cortex-M0+，32 KB Flash / 4 KB RAM），70 个 C 文件（HAL 库全套）加启动汇编。arm-none-eabi-gcc -mcpu=cortex-m0 -mthumb 交叉编译，全量构建通过：

• RAM 占用 2432 B / 4 KB（59.38%）
• FLASH 占用 6720 B / 32 KB（20.51%）
• Project.elf / Project.hex / Project.bin 三个产物完整生成

本机与手机耗时对比

本机首次全量编译 21 秒，之后稳定在 5-6 秒，差距来自磁盘冷缓存与杀毒软件首次扫描。手机稳定在 40-44 秒，约为本机的 7-8 倍。

Web 后端：mongoose + SQLite

同一个沙盒里跑另一个 demo：C 语言 mongoose 库起 HTTP 服务器，SQLite 存数据，前端 HTML 页面对接增删查接口。浏览器直接访问手机 IP 即可操作，增删查和搜索全部在手机本地完成。这一套环境同样没有进入主力机，验证完即弃。

八核并行收益与瓶颈

手机是 8 核，-j8 只比 -j4 快 4 秒。瓶颈不在 CPU 并行度，在 proot 虚拟化层的 IO 开销：每次文件读写都要经过 proot 路径翻译，编译过程大量临时文件的读写放大了这部分开销。手机单核性能本身也弱于主力机，并行无法补偿。

适用边界

值得用手机沙盒的场景：AI 驱动的工具链安装实验、交叉编译环境反复装包卸包的测试、Web 后端 demo 验证、需要隔离环境跑脚本。日常高频编译仍用主力机，6 秒与 40 秒的差距不值得为隔离付出。

边界两条：proot 容器无 root，涉及设备映射或特权操作受限；交叉工具链必须是 Linux aarch64 版本，与容器 libc 匹配。

概述

是一个中途接手的救火项目。设备包含一个计时器组件，可显示计时的小时、分钟、秒。MCU 使用内部晶振，通过 I²C 连接外部 TCXO RTC；MCU 内部定时器提供毫秒级计时，外部 RTC 负责长期时间基准，并通过中断信号通知 MCU 秒级时间边界。虽然 RTC 本身还提供高精度时钟输出，但硬件设计并未将其接入 MCU。

这种双时钟架构带来了一个问题：片内定时器响应快、分辨率高，但长期会漂移；外置 3PPM RTC 长期稳定，但通过 I²C 只能获取秒级时间边界。开始计时的时机又完全随机，例如整秒后的 0.9 秒开始计时，RTC 再过 0.1 秒就跳秒，导致计时刚开始就显示 1 秒，暂停后继续时也会出现同样的跳变。

硬件已经定型投产，无法改板，因此只能通过软件协调两套时钟，在不改变硬件的情况下兼顾长时精度与计时显示的连续性。

解决

1. 痛点：外部 RTC 负责长期精度，但秒级时间边界与随机开始计时的时刻无法对齐；内部定时器则无法独立承担长时计时。
2. 解法：开始计时记录当前相位，测量到下一次 RTC 秒中断边界的时间差（0～1 秒），不立即修正，而是将相位差在后续 60 秒内渐进消化，避免显示跳变。暂停后继续时重新建立相位基准。
3. 结果：保留片内定时器的毫秒级响应，同时以 3PPM 外部RTC 作为长期时间基准，消除开始、暂停、继续过程中的秒级跳变；在硬件冻结的情况下，仅通过软件解决两个时钟时间尺度不一致的问题。
4. 根治：直接使用外部 TCXO 时间源为 MCU 提供高精度时间基准，使计时与 RTC 共用同一时钟源，从硬件层面消除两套时钟之间的相对漂移。

概述

设备内置调试页面，每 5 秒自动刷新任务列表与内存水位，用于前期研发调试，便于远程观察运行状态；页面数据由设备 Web 服务在运行时遍历任务列表生成。

该功能长期运行稳定。某次自动刷新后，任务列表出现数百行重复条目，内存水位降至 16 字节，设备失去响应并重启。以下记录现象、复现过程与根因判定。

现象

调试接口 /debug.json 由页面每 5 秒自动刷新，返回任务列表和内存水位。某次刷新后，任务列表出现同一批任务的几百行重复条目，堆的"历史最低剩余"掉到 16 字节，设备失去响应并重启。

复现

最小复现工程：一个任务每毫秒创建并删除子任务，另一个任务反复调用 xTaskGetNext() 遍历并统计每个任务句柄的返回次数。

第一轮统计把"句柄重复"当信号，被 FreeRTOS 的句柄复用干扰（子任务删除后新任务复用同一内存地址），数据虚高。改为只统计永不删除的持久任务后，结论稳定：遍历期间任务被增删时，迭代器会卡在同一段列表反复重走，5000 次调用都不返回结束标志；挂起搅动任务后异常消失。

官方回复

issue 提交后，Espressif 维护者 igrr 回复：

These private functions are intended to be used in debug contexts: GDB Stub, Core Dump, where iteration over the list of tasks happens while the application isn't running.

这些私有函数只用于调试场景：GDB Stub、Core Dump，且这些场景在应用未运行时遍历任务列表。翻译成大白话：这是调试专用工具，设计前提是遍历时应用不运行、任务列表不动。我们把它用在了运行中的系统里，遍历期间任务增删导致卡住。

官方回应的边界成立，但它不消解缺陷本身：代码显式写了“遇到失效节点”的分支，正确的处理应当跳过并推进迭代器状态，或无法推进时返回 -1 终止；实际实现却只跳过不推进，形成无限循环。错误处理路径本身有 bug，这一点与“调试专用”的定位无关，后者只解释了它为何长期未被触发。

issue：#19022，复现工程：esp-idf-xtaskgetnext-repro。

结论

经排查：设备调试页面按 5 秒周期刷新任务列表，在任务频繁创建、删除的运行环境下，xTaskGetNext() 遍历出现不结束现象。迭代器反复重走同一段列表，单次刷新产生数百行重复条目，堆的历史最低水位降至 16 字节，设备失去响应并重启。

经最小复现工程验证，该现象可稳定复现：遍历期间存在任务增删时，迭代器连续 5000 次调用不返回结束标志；任务增删停止后，异常消失。

经分析，根因在 xTaskGetNext() 的错误处理路径：代码为“遇到失效节点”写有处理分支，但该分支仅跳过当前节点、不推进迭代器状态，遍历因此无限循环且不返回结束标志。该缺陷属“遍历中修改容器”一类已知缺陷，触发与否取决于运行场景，缺陷本身不随场景变化。

界面跑在立创实战派 ESP32-S3 上，由 LVGL 9.5 渲染。要进文档只能对着屏幕拍照；模拟器又覆盖不了实机行为，AI 要验证界面必须碰真机。我给设备加了一个网页截图接口：浏览器点一下，LVGL 当前画面变成 BMP 图片回传。这个接口同时服务文档整理和 AI 视觉闭环。

实机界面是 AI 视觉闭环的入口

LVGL 有 PC 模拟器，能跑布局和事件逻辑，但触摸采样、手势轮询、局部刷新时序都依赖真实硬件。模拟器跑不全的界面状态，只能在实机上出现，AI 也就只能在实机上确认。截图接口把实机画面变成机器可读的图片，AI 用视觉模型识别界面状态，再决定下一步构建或修复，形成闭环。文档截图只是这个接口的副产物。

总体链路

请求从浏览器出发：点「截图」→ GET /screenshot → HTTP 任务把参数写进截图请求结构 → 显示任务用 LVGL 快照渲染当前屏到 PSRAM 缓冲 → BMP 编码逐行流式回传 → 浏览器 blob 预览和下载。

链路的硬约束是 LVGL 线程模型：渲染只允许在显示任务内发生，HTTP 任务不能碰渲染 API。两端用「请求结构 + 二进制信号量」握手。

显示任务内的 LVGL 快照渲染

HTTP 服务器任务收到请求后，把宽高、目标缓冲、完成信号量写进全局请求槽。显示任务每帧轮询这个槽，消费后渲染，完成后发信号量，调用方阻塞等待。

渲染调用 lv_snapshot_take_to_draw_buf，把一个 lv_draw_buf_t 指向调用方提供的 PSRAM 缓冲，目标是当前激活屏。前置条件是 CONFIG_LV_USE_SNAPSHOT=y，这个开关默认关闭。缓冲按 320×320×3 预留，RGB888 每像素 3 字节。

RGB888 捕获消除 RGB565 偏色

第一版用 RGB565 捕获，网页里看界面背景偏绿。逐像素算过：设计色 (237,237,237) 存进 RGB565，G 通道 6 位向上取整到 59，展开回 8 位变成 253；R、B 各 5 位向下取整到 29，展开 239。结果 (239,253,239)，绿色高了一截。

屏幕本身就是 RGB565，面板上实际显示的也是这个偏色，截图忠实还原了面板。文档要的是设计原色，所以捕获格式改成 RGB888，渲染器直接输出 24 位，背景精确回到 (237,237,237)。

字节序顺带省事：LVGL 的 RGB888 内存序是 B,G,R（LV_COLOR_MAKE 宏展开为 {b8,g8,r8}），正好是 BMP 的字节序。逐行 memcpy 直接发送，省掉逐像素转换。

BMP 流式回传

编码结果流式发送，不整张缓存。先发 54 字节 BMP 头，再按行从底到顶 httpd_resp_send_chunk。320×240 的 24 位 BMP 约 230KB，设备侧只需 307KB 的 RGB888 快照缓冲，输出侧零大缓冲。

网页端截图按钮

页面顶部工具栏加「📷 截图」按钮，fetch('/screenshot') 取回 blob，URL.createObjectURL 生成预览，弹窗内可下载 BMP。更新网页文件走文件管理器的 /api/fs 上传接口，不重烧 littlefs 镜像，避免覆盖设备上已保存的配置。

两个落地时的坑。一是 httpd 的 max_uri_handlers 默认 8，平台各端点注册完是 17 个，撞满当时 16 的上限，静态回退注册直接触发 ESP_ERROR_CHECK 重启，上限改成 24 解决。二是第一版按钮点了没反应，检查发现页面里 takeScreenshot 函数没有写进去，此后每次改网页都用 curl 校验函数存在。

适用边界

接口提供一次性截图，实时投屏需要定时轮询和更高压缩率的编码，本实现没有做。BMP 无压缩，单帧约 230KB，适合调试和文档。AI 闭环目前按「截图 → 视觉识别 → 决定下一步」的节奏工作，瓶颈在识别刷新率，截图链路本身开销很小。

HTML/CSS 搭的尘埃粒子计数器面板。下面是两个组件的设计提示词，加上拨杆声的合成参数。demo 可以直接点。

实物参考

复刻自一台真实的 RION 尘埃粒子计数器（下图），整体配色与走线照它来。

点阵数码管组件

• 结构：每个数字是一块 5×7 的小圆点矩阵，点为正圆。
• 点亮态：绿色荧光圆点，中心偏白高光，带一圈绿色光晕（radial-gradient 渐变 + box-shadow 发光）。
• 熄灭态：深绿色小圆点，隐约留下点阵网格，像没有通电的位。
• 布局：10 位显示区，数字右对齐，左边未使用的位只显示暗点。
• 底板：深色玻璃感，内凹，边缘有微弱反光。

拟物风格按键

• 按钮：正方形凸起键帽、圆角，顶面高光、底边暗边，用 linear-gradient 模拟受光。
• 指示灯：圆形琥珀灯装在按钮面板中央（灯在按钮上）。点亮为琥珀橙 #e89400 带光晕；熄灭为深色含琥珀调 #5f5340。

为什么熄灭态不落到纯黑：跟点亮的琥珀橙同属一套色相，整排灯看起来是同一批元件；暗态也能辨认这是琥珀灯珠，不会和滑槽阴影糊在一起。真实 LED 灯珠未点亮时，透光外壳往往带自身颜色，纯黑会失真。

• 文字：档位标签印在按钮外面的滑槽下方，避免随按键移动。
• 滑槽：凹进去的槽（inset box-shadow），四周留白统一，按钮不重叠。
• 机箱：米白金属外壳、顶部饰边、品牌标识。
• 交互：按下按钮本体下压（translateY 2px + 阴影收缩）。

按压与拨杆声的合成参数

用 Web Audio 实时合成，三个声源叠加：blip + noise + thump。

blip（咔哒主音）

• 振荡器：square / triangle
• 对数频率斜坡：f(t)=f0·(f1/f0)^(t/T)
• 指数衰减增益：g(t)=v·e^(−t/τ)，τ=T/ln(v/0.0001)
• 参数：老式键 f0=1450, f1=420, T=0.03, v=0.6；拨杆 f0=960, f1=500, T=0.04, v=0.42

noise（机械颗粒）

• 白噪声线性衰减：n[i]=(2·rand−1)·(1−i/N)
• 高通滤波：fc≈900–1600Hz
• 参数：T≈0.016–0.032, v≈0.26–0.34

thump（低频共鸣）

• 正弦频率斜坡：f(t)=F·(0.45)^(t/T)
• 参数：F≈200Hz, T≈0.05, v≈0.3–0.34

1. 概述

单向电机可以用数字霍尔开关计数。磁铁每转一圈经过霍尔一次，输出完成一次激活和释放，产生两个边沿；固件把这一对边沿记为一个计数脉冲。

现有方案需要在电机停稳后切断霍尔电源以降低功耗。本文默认断电期间电机不动。重新上电后，霍尔会丢掉断电前的内部状态，按上电瞬间的磁场重新判决。单霍尔一圈只有一个计数脉冲，计数值无法说明停靠点落在进入临界区还是离开临界区。前后输出一致，也不能证明已经离开临界区。必须关断霍尔电源时，应先让停靠点以较大概率离开这两个临界区。

2. 迟滞区

数字霍尔开关有两个阈值：Bop 进入激活，Brp 退出激活。沿磁铁路径，它们对应两个临界区：

• 进入临界区：靠近 Bop，即将从释放变为激活。
• 离开临界区：靠近 Brp，即将从激活变为释放。

中间是稳定激活区，外侧是稳定释放区。迟滞防止边界附近反复跳变，也留下状态记忆。断电会清掉这份记忆。上电后若停在任一临界区，器件重新判决；单霍尔读不出停在进入侧还是离开侧。前后输出一致，也不能证明已经离开临界区。

电机转一圈产生两个边沿，并合成为一个计数脉冲，计数位置精度是 1 圈。两个临界区分别位于一次电平周期的两处边界；区分它们需要知道磁铁处于一圈中的哪半段，相当于至少 0.5 圈的相位分辨率。仅凭整圈计数值无法确定停靠点靠近哪一处临界区。

现有磁路和转速约束已经确定使用数字霍尔开关。器件型号及选型参数不展开，下文只讨论霍尔断电后丢失迟滞状态造成的计数偏差。

迟滞区临界情况分析

符号约定

本节只分析停靠点处于临界区时，霍尔断电再上电产生的状态重判。上下电期间的电源暂态和假脉冲已由固件单独排除，不进入以下边沿计数。

屏蔽中断时直接计数

霍尔低功耗断电期间屏蔽边沿中断，重新上电并等待输出稳定后再恢复计数。一次完整旋转正常产生 2 个边沿，并合成为 1 个计数脉冲。停靠点处于临界区时，实际结果可能是 1 个、2 个或 3 个边沿。

霍尔断电时电机位置不变，重新上电后再继续旋转。按临界区位置、断电前电平和上电稳定后电平枚举，共有 8 种情况：

断电前后电平不变的 4 种情况不会改变边沿序列。电平发生变化的另外 4 种情况分成两类：

• 丢失一个边沿：真实边沿发生在中断被屏蔽期间，预期计数为 2，实际只计到 1。
• 多计一个边沿：上电后的重新判决被当成运动边沿，预期计数为 2，实际计到 3。

两类错误方向相反。在两个临界区和两种重判方向等概率的理想条件下，长期平均值可能互相抵消；单次停机或单台设备的计数不能依赖这种抵消。

不屏蔽中断时的计数偏差

不屏蔽边沿中断后，原本在断电重判期间被屏蔽的边沿也会进入计数。丢失边沿的场景因此恢复为预期 2 个边沿、实际 2 个边沿。

多计边沿的场景会从 3 个增加到 4 个。正常旋转产生一次激活和一次释放，共 2 个边沿；临界区重新判决又产生一个边沿，继续旋转到稳定区时还会产生一个恢复边沿。中断全程开启后，这两个额外边沿都会被计入，所以结果是预期 2 个、实际 4 个。

严格边沿配对的欠计数

严格边沿配对同时检查边沿方向、先后顺序和时间间隔。收到第一个预期边沿后，软件进入等待状态；只有相反方向的第二个边沿在有效时间窗口内到达，才组成一对并形成一个计数脉冲。等待超时后，未完成的配对被清除，避免拿下一圈的边沿补配当前边沿。

严格边沿配对可以过滤多计边沿的情况，使预期 2 个边沿、实际 2 个边沿；但丢失一个边沿时，剩余边沿无法组成完整配对，整组边沿都会被舍弃，预期 2 个边沿、实际 0 个边沿。

边沿奇偶校验只能标记奇数边沿，无法恢复已经丢失的边沿。若把奇偶校验作为计数有效性的门槛，奇数边沿会被整组舍弃，结果等同于严格配对；若临界区额外产生一对边沿，实际边沿数为 4，简单奇偶校验也无法识别。

结论

三种策略的代价如下：

正常的一圈为 2 个边沿、1 个计数脉冲。在这组临界区枚举下，屏蔽中断后直接计数的单次误差为 ±1 个边沿；不屏蔽中断可能多出完整的一对边沿，严格配对可能丢掉完整的一个计数脉冲。因此，必须在单霍尔断电的前提下继续计数时，屏蔽中断并直接计数的代价相对可控，但它仍然不能消除临界区带来的不确定性。

3. 实验现象

用示波器同时监测霍尔供电（绿色，外部手动通断）与霍尔输出（黄色）。把磁铁分别停在触发位、非触发位与临界区，观察两块样品反复上电、下电时的输出。

位置	样品 A	样品 B
触发位
非触发位
临界区

对应现象如下：

实验给出两点。第一，上电后过早打开中断会把启动尖峰和暂态台阶计进去；正确顺序是先给霍尔供电，等待输出稳定，清除旧中断标志，最后再恢复计数。第二，稳定区的最终输出通常可复现，临界区则不然。样品 A 在临界区反复上电时输出可能翻转；样品 B 多数时候前后一致，但这份一致不能证明它已经离开临界区，更不能说明它停在进入侧还是离开侧。霍尔持续供电时，计数通常更稳定，因为器件状态没有被清掉。

4. 解决办法

方案一：出厂标定停靠参数

这是概率缓解，无法保证形式正确。单霍尔给不出 0.5 圈的位置，所以不去解“现在停在哪个临界区”。每台机器出厂时，用惩罚函数学习一组电机停靠参数，让电机自己停下来时，有较大概率落在安全区。

它成立有三个前提：

• 温度漂移：Bop / Brp 会随温度、批次和老化平移。出厂标的是这台机器、这只霍尔当时的迟滞宽度。换料号，或跑数年以后，原来的安全区可能缩进临界区。
• 电源暂态：上电尖峰、掉电陡坡和供电波动会改变霍尔的重新判决。标定环境若和现场供电差太远，样本无效。
• 电机可控：惩罚函数学的是停机参数，电机必须能按这组参数重复停到相近位置。停点散差大于安全区宽度时，标定没有意义。

惩罚函数的核心观测是一次断电再上电的霍尔输出：

• 前后不一致：这次停靠点让霍尔重新判决翻了面，给明确惩罚。
• 前后一致：只说明这一次没有翻面，不能当成已经安全，最多给较弱奖励。

对同一台设备反复停机、断电、上电，就能采到一批样本。学到的参数要留 margin，覆盖 Bop / Brp 的温度、批次和老化漂移，以及磁路偏差和电机停点散差；具体余量由实际标定数据确定，不能只靠多次断电样本把翻面概率压低。标定结果随机器保存，后续休眠时按这组参数停机，再关闭霍尔电源。

方案二：双霍尔判别区间

把两个霍尔错开安装。两路输出的组合可以直接给出磁铁所在区间；其中一路接近进入或离开阈值时，另一路仍能提供稳定判断。

5. 结论

单霍尔计数在持续供电时是可靠的。一旦切断霍尔电源，软件就不知道停靠点落在进入临界区还是离开临界区。一个由两边沿组成的整圈计数脉冲分辨不出停在哪一侧；断电前后输出一致，也不能证明已经离开临界区。

必须关闭单个霍尔电源时，出厂标定只能降低停进临界区的概率，并要给 Bop / Brp 留 margin；它缓解计数偏移，并不保证形式正确。需要连续且准确的计数时，应保持霍尔供电，或改用至少两个霍尔传感器。

概述

设备通过 BLE 配网（BluFi）：手机连上配网蓝牙、下发 WiFi 凭据，设备以 STA 方式连接路由器。配网期间 WiFi 与蓝牙必须同时工作，但 ESP32 的 WiFi 与蓝牙共用同一射频前端，单射频按时分复用（TDM）调度，射频资源由共存仲裁器按优先级分配；官方共存矩阵将部分组合的蓝牙性能仅定性为 C1（支持但性能不稳定）。

某次配网中，WiFi 密码错误、路由器暂时不可达，STA 进入反复重连。此时手机能连上配网 BLE、能订阅通知，但设备主动下发的数据全部消失，点“扫描 WiFi 列表”无任何回包。以下记录现象、排查过程与根因判定。

现象：连得上，发不出

环境是 ESP-IDF v6.1-beta1，NimBLE，BluFi 配网。WiFi 一次就能连上时，整条配网流程正常。一旦 STA 进入反复重连，故障变成状态相关的：

• 手机能扫到设备，能连上配网 BLE，也能订阅通知。
• 手机写下发命令，设备收得到、也处理得了。
• 设备该回给手机的数据全部消失：WiFi 列表没有，状态报告也没有。

链路层是通的，GATT 写是通的，唯独板子主动发给手机的蓝牙包发不出去。

第一层：WiFi 重连把蓝牙射频挤掉

ESP32 的 WiFi 与蓝牙共用同一射频前端，同一时刻只有一个模块能用空口，由共存仲裁按优先级分配（TDM 时分复用）。WiFi 扫描、重连这类活动期间，蓝牙被持续压制，空口丢包、序号错乱时有发生。

官方共存矩阵将 WiFi 处于 SoftAP 连接中/已连接、Sniffer RX 时的蓝牙性能标为 C1（支持但性能不稳定）；STA 与 BLE 的组合官方标 Y（支持且稳定），但官方 issue 与 FAQ 里仍有大量共存故障记录：ESP-IDF #17871（ESP32-S3 仅在 BLE 激活时 STA 掉线，关闭 BLE 即恢复）、#11280（ESP32-C3 共存下 BLE 连接建立后立即失败，已修复）、FAQ ELx200（Wi-Fi 与 BLE 共存时频繁报错，官方给出修复）。本案例的 STA 反复重连属于重连风暴（反复扫描与重连），实测对蓝牙的压制同样明显。

STA 反复重连时，外设刚连上，NimBLE 还要补发一条 LE Read Remote Version Information 读对端版本。这条 HCI 交换正好撞上仲裁窗口，控制器回 HCI 错误 0x1A（26，Unsupported Feature or Parameter Value）。

如果只是空口被挤占，收和发应该一起变差。现在接收还在，只有板子往外发的包没了，说明射频干扰只是第一层。真正把发送通道关掉的，是后面那条库逻辑。

第二层：NimBLE 把读版本失败当成连接失败

BLE_GAP_EVENT_CONNECT 的 status 在 NimBLE 里有多处赋值。逐一排除后，只有 ble_gap_rx_rd_rem_ver_info_complete() 会把任意 HCI 状态原样带进连接事件。

读版本 HCI 事务完成后，完成事件里的 ev->status 被直接当成连接事件 status，丢给广播回调，也就是 esp_blufi 的 GAP 回调。仲裁干扰让这条命令失败后，esp_blufi 打出 connection failed; status=26。连接其实已经建立了，失败的只是事后读版本。

后果：is_connected 恒为 false

esp_blufi 用一个布尔量 is_connected 判断能不能往手机发数据。它只在连接事件 status == 0 时置位。连接事件被污染后，这个标志永远是 false。

btc_blufi_send_encap() 看到 false 直接返回。状态报告、WiFi 列表，所有板子到手机的数据都被静默丢掉。接收方向不查这个标志，所以手机写进来的请求照常处理。表现就是“连得上、发不出”。

上游已经修了库 bug，但还没进当前 IDF

相关 issue 是 espressif/esp-idf #18342 "Blufi connect error in Nimble"，同属 BluFi + NimBLE 连接错误这一块。

这次定位到的具体路径，已经在上游 mynewt-nimble 修掉：连接事件 status 固定为 0，读版本、读特性改成连接事件投递之后的独立 HCI 事务，失败不再污染连接状态。ESP-IDF 对应迁移是 e08609e451 "Migrate to NimBLE 1.9.0"（2026-07-25）。v6.1-beta1、v6.0.2、v6.1-rc1 都还没带上。

现在能用的两步处理

两层原因对应两步处理：

• 修库 bug：IDF 本地补丁，slave 分支里把 ble_gap_event_connect_call(ev->conn_handle, ev->status) 改成 ble_gap_event_connect_call(ev->conn_handle, 0)，和上游语义对齐。
• 躲开仲裁打架：手机明确请求扫描 WiFi 列表（GET_WIFI_LIST）时，wifi_manager_suspend_sta() 先挂起 STA 自动重连，SCAN_DONE 立刻恢复。普通退避重连不要动。

升级到带 NimBLE 1.9.0 的 IDF 后，本地补丁可以拿掉。补丁改的是 IDF 安装目录，升级会丢，更新后要重新打。

补丁前后对照

用 PC 蓝牙模拟手机（bleak 直连，按 BluFi 帧格式发 GET_WIFI_LIST）：

• 补丁前：PC 收到 0 条通知。
• 补丁后：收到 WiFi 列表通知，158 字节，里面是真实 SSID。

根因和修复都在硬件上对过。

结论

本设备通过 BLE 配网（BluFi），配网期间 WiFi 与蓝牙同时工作，但两者共用同一射频前端，由共存仲裁时分复用。

经核查，故障属实：WiFi 正常时配网流程可用，WiFi 反复重连后，设备下发的数据全部丢失。

原因分两层。WiFi 与蓝牙共用射频前端，重连期间仲裁持续压制蓝牙，读版本 HCI 命令失败（0x1A），空口丢包、序号错乱时有发生；NimBLE 又将该失败状态写入连接事件，esp_blufi 的 is_connected 恒为 false，发送通道被静默关闭。

验证与处置：PC 蓝牙直连下，补丁前 0 条通知，补丁后收到 158 字节真实 SSID。软件层已由上游 NimBLE 1.9.0 修复；硬件层属共存特性，扫描 WiFi 列表时挂起 STA 重连即可规避。

MQTT消息放在RAM队列中，设备一旦掉电，未发出的消息会全部丢失。

将消息先写入FlashDB，收到Broker ACK后再标记删除，设备重启时扫描未删除的记录继续发送，即可解决这个问题。

核心判断标准：记录存在代表消息未完成，标记删除代表处理完成。

RAM队列的问题

MQTT发布包含两个阶段：设备将消息交给客户端，客户端等待Broker回ACK。两个阶段之间如果发生掉电，RAM中的消息无法恢复，Broker永远收不到。

因此需要一个掉电不丢失的本地队列。FlashDB TSDB模式支持追加写入、顺序遍历、重启后数据保留，适合作为这个队列的存储层。

存储设计：数据与状态分离

TSDB每条记录由消息内容和状态索引组成。状态存储在索引中，更新状态时无需重写整条消息。

业务层只需要两个状态：

• FDB_TSL_WRITE：记录存在，消息未完成
• FDB_TSL_DELETED：已收到ACK，标记删除，等待FlashDB回收

"等待ACK"是发送过程中的临时阶段，不需要落盘。重启时该消息会被重新发送，存储该状态没有意义。

发送流程

每轮处理从最老的一条FDB_TSL_WRITE记录开始：

1. 查询队头第一条待发送记录
2. 读取记录内容，发送消息
3. 等待ACK
4. 收到ACK后，删除该条记录
5. 重新查询队头，处理下一条

发送函数不直接修改数据库状态，删除作为独立操作执行。删除时从数据库重新查找第一条WRITE记录，不依赖发送函数传递的句柄或位置。这样发送和删除职责清晰，故障排查路径明确。

掉电场景与投递语义

ACK与删除是两个独立动作，中间的掉电窗口无法消除。各场景下的行为如下：

该方案选择**At-Least-Once（至少一次）**投递语义，宁可重复、不丢消息。消息去重由MQTT QoS机制或业务层消息ID处理。

边界与扩展

• 适用消息：Flash写入有擦写寿命和延迟开销，该方案适合QoS 1/2的高价值消息（如控制指令、告警、状态变更、计费数据）。高频、可丢弃的采样数据（如每秒一次的传感器读数）直接走RAM队列即可，落盘收益抵不过Flash磨损和吞吐开销。是否落盘应由业务层按消息类型决定，不要一刀切。
• 并发发送：该设计默认单发送任务。多任务并发时需要增加互斥锁和领取机制，避免多个任务取到同一条记录。
• 容量限制：单条消息长度受TSDB初始化时的最大长度配置约束，总容量受Flash扇区大小限制，需要根据业务场景设计旧消息淘汰策略。
• 状态扩展：TSDB自定义状态槽位数量固定，不建议占用状态位存储重试次数、消息类型等信息。这类数据可以放在消息内容的业务头部，自定义格式解析。

声明： iotspool 是一个开源项目，作者为 Vanderhell。本文是阅读该项目源码和文档后整理的学习笔记，用于理解嵌入式持久化消息队列的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/iotspool

上一篇讲怎么用。这篇只讲三个选择：消息怎么落盘、掉电怎么认账、Broker 挂了怎么重试。

只追加，不回头改

设备要保证采样到的数据在断网、掉电、Broker 重启之后还能发出去。RAM 顶不住，Flash 又不能随便改——写一半断电，文件就脏了。

落盘因此只允许两种笔：

• 入队：在文件尾巴追加一条 ENQ，带编号、主题和正文。确认落盘，才算收下。
• 确认：发送成功后不回去改那条 ENQ，再追加一条 ACK，只带同一个编号。

日志永远往前长。掉电窗口只剩一种：最后一条可能写了一半。中间已经落盘的记录，不会被一次半截写入弄脏。

编号单调往上加。ACK 靠编号对上当初那条 ENQ。校验盖住整条记录；半截或校验失败，恢复时一律当脏尾巴丢掉。

恢复就是顺序扫一遍

开机从文件头扫到尾：

1. 完整且校验通过的 ENQ，记成待发。
2. 扫到对应 ACK，从待发里拿掉。
3. 读到半截或校验不过，截到上一条完整记录，停。

半截永远不重放。ACK 如果刚好没写完，最坏是这条再发一次——至少一次，不会丢已经确认过的。

内存不囤正文，只记编号、位置和长短。待发条数决定 RAM，消息大小不影响。发送那一刻再按位置读出来。

文件会因为历史 ENQ 和 ACK 越滚越大。满了就把还没发出去的 ENQ 整本抄到新文件，原子换掉旧的。已确认的全部扔掉。不做段回收，逻辑短，也好验证。

重试要打散

一群设备同时掉线，如果都按同一个固定间隔重试，窗口一到会一起砸 Broker。

所以失败后把等待上限翻倍并封顶，真正等到的时间在 0 到上限之间随机抽。发出去之后，上限收回去。调用方只问“现在有没有到期该发的”，不用自己算钟。

边界

• 文件还是 Flash，库不管，只要能追加、按位置读、确认落盘、截尾巴、整份替换。
• 默认假定调用是串行的。两个任务同时摸队列，自己加锁；中断里不要直接入队。
• 它不管 MQTT 协议，不管加密，也不保证只投递一次。重复送达上层去重。

三句话：写入永远只追加；恢复只砍尾巴；内存只记位置，文件大了整本重抄。

声明： iotspool 是一个开源项目，作者为 Vanderhell。本文是阅读该项目源码和文档后整理的学习笔记，用于理解嵌入式 MQTT 场景下持久化 store-and-forward 队列的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/iotspool（MQTT publish 的持久化 store-and-forward 队列，掉电不丢消息）

做物联网设备的人迟早要踩同一个坑：数据到了发送这一刻，网络断了、Broker 重启了、或者设备自己掉电了。直接 mqtt_publish() 就赌它成功，赌输了就是数据默默消失；自己在 RAM 里攒 FIFO，一掉电全没；往 Flash 里随便写，写一半断电文件就坏。

iotspool 专门填这个坑：一个零依赖的 C99 库，把 MQTT PUBLISH 消息写进 append-only 日志，CRC 校验，掉电自动截断尾部半截记录，Broker 不可达时指数退避重发，成功后才把 ACK 落到磁盘。支持 Linux、ESP-IDF、STM32 等裸机环境，coreMQTT/Paho/mosquitto/自研 MQTT 客户端都能对接。

它解决什么问题

嵌入式 MQTT 上报的常见故障模式：

• 瞬时断网：路由器重启、基站切换，几秒到几十秒恢复。RAM FIFO 能顶一阵，但满了之后丢谁、留谁要自己定策略。
• Broker 不可达：云端升级、证书轮换，可能持续几分钟到几小时。RAM 顶不住，必须落盘。
• 设备意外重启：看门狗复位、掉电、HardFault。RAM 里未发送的消息全部丢失。
• 写入中途断电：消息写了一半电没了，下次启动不能读到半截脏数据。

iotspool 给每一条待发消息分配一个单调递增的 msg_id，把 ENQ（入队）记录追加到存储文件，写完后 fsync（或等价操作）；发送成功后再追加一条 ACK 记录标记该 msg_id 已确认。下次启动时 iotspool_recover() 扫一遍日志，尾部 CRC 不完整的半截记录直接丢弃，其余未被 ACK 的 ENQ 重新进入待发队列。

五分钟在 Linux 上跑通 Demo

下面是最小可运行示例，逻辑对应仓库里的 examples/rpi/main.c，做了精简。

1. 编译

git clone https://github.com/Vanderhell/iotspool.git
cd iotspool
cmake -S . -B build -DIOTSPOOL_BUILD_TESTS=ON
cmake --build build -j

仓库自带 POSIX 存储后端 src/store_posix.c，Linux/macOS/ESP-IDF VFS 都能直接用。STM32 等裸机环境需要自己实现 iotspool_store_t 的 5 个回调（append / read_at / sync / size_bytes / truncate_to / replace），对接到 raw Flash 或 LittleFS。

2. 最小发送循环

#include "iotspool.h"
#include "../../src/store_posix.h"
#include <stdio.h>
#include <string.h>
#include <time.h>

static uint32_t now_ms(void) {
    struct timespec ts;
    clock_gettime(CLOCK_MONOTONIC, &ts);
    return (uint32_t)(ts.tv_sec * 1000 + ts.tv_nsec / 1000000);
}

/* 替换成你自己的 MQTT 客户端发布函数，返回 0 表示成功 */
static int fake_mqtt_publish(const char *topic, uint32_t topic_len,
                             const uint8_t *payload, uint32_t payload_len,
                             uint8_t qos) {
    printf("  [MQTT] %.*s -> %.*s (qos=%d)\n",
           (int)topic_len, topic,
           (int)payload_len, (const char *)payload, qos);
    return 0;
}

int main(void) {
    /* 1. 打开存储文件 */
    iotspool_store_t store = {0};
    if (store_posix_open("/tmp/spool.bin", &store) != IOTSPOOL_OK) {
        fprintf(stderr, "open store failed\n");
        return 1;
    }

    /* 2. 初始化 + 从磁盘恢复未发送队列 */
    iotspool_cfg_t cfg = iotspool_cfg_default();
    cfg.max_store_bytes    = 512 * 1024;  /* 最多占 512KB */
    cfg.drop_oldest_on_full = true;      /* 满了丢最老的，保新数据 */
    cfg.min_retry_ms = 1000;
    cfg.max_retry_ms = 60000;

    iotspool_t *spool = NULL;
    iotspool_init(&spool, &cfg, &store);
    iotspool_recover(spool);   /* 空文件上调用也是安全的 */

    /* 3. 业务侧入队：传感器采样后直接 enqueue，不等网络 */
    const char *payload = "{\"temp\":23.7,\"humi\":58}";
    iotspool_msg_t m = {
        .topic       = "factory/line1/env",
        .topic_len   = (uint32_t)strlen("factory/line1/env"),
        .payload     = (const uint8_t *)payload,
        .payload_len = (uint32_t)strlen(payload),
        .qos         = 1,
        .retain      = false,
    };
    iotspool_msg_id_t id;
    iotspool_enqueue(spool, &m, &id);

    /* 4. 网络任务里的发送循环 */
    iotspool_msg_t out = {0};
    iotspool_msg_id_t out_id = IOTSPOOL_MSG_ID_INVALID;

    if (iotspool_peek_ready(spool, now_ms(), &out, &out_id) == IOTSPOOL_OK) {
        if (fake_mqtt_publish(out.topic, out.topic_len,
                              out.payload, out.payload_len, out.qos) == 0) {
            iotspool_ack(spool, out_id);          /* QoS0 在发送成功后调 */
        } else {
            iotspool_on_publish_fail(spool, now_ms());  /* 触发退避 */
        }
    }

    iotspool_stats_t st;
    iotspool_stats(spool, &st);
    printf("pending=%u acked=%u store=%u bytes\n",
           st.pending_count, st.acked_total, st.store_bytes);

    iotspool_deinit(spool);
    store_posix_close(&store);
    return 0;
}

运行仓库自带的完整示例：

./build/example_rpi

输出会显示 5 条传感器读数入队、随后被逐个取出、ACK 后统计归零。

3. 对接真实 MQTT 客户端的关键约定

QoS 2 当前不在库的支持范围内。库保证 QoS 1 跨重启的 at-least-once 语义，重复送达由上层去重。

配置项速查

iotspool_cfg_default() 返回默认值，按需改：

• max_pending_msgs：RAM 里索引的最大消息条数（默认 64）。超过这个值再 enqueue 会返回 IOTSPOOL_EFULL，除非开了 drop_oldest_on_full。
• max_store_bytes：存储文件最大字节数（默认 256KB）。
• max_payload_bytes / max_topic_bytes：单条消息 payload/topic 的上限，用于内部分配 scratch。
• min_retry_ms / max_retry_ms：退避区间，默认 1s 到 60s。
• drop_oldest_on_full：队列满时是否丢最老消息。设为 false 时 enqueue 直接返回 IOTSPOOL_EFULL，由调用方决定丢还是等。
• enable_sha256：是否给每条记录加 SHA-256 校验（默认关，CRC32 已够检测掉电半截）。
• lock / unlock：多任务环境下传入互斥锁回调，核心 API 执行前自动加锁。ISR 不可直接调库，除非锁回调能在 ISR 中返回 IOTSPOOL_EBUSY。

掉电恢复的启动顺序

推荐的开机流程：

1. 挂载文件系统（或初始化 Flash 驱动）。
2. 打开 store 后端（store_posix_open 或自定义 vtable）。
3. iotspool_init / iotspool_init_inplace。
4. iotspool_recover。
5. 启动传感器采样任务和 MQTT 发送任务。

这一步必须放在 MQTT 连接之前，否则连接一建立、publish 任务开始跑，但队列状态还没重建，可能漏发重启前积压的消息。

嵌入式无堆环境的用法

默认 iotspool_init 会 malloc 内部索引和 scratch 空间。STM32 等不想用堆的场合，用静态内存版本：

iotspool_t spool;
iotspool_entry_t entries[64];                     /* RAM 索引 */
uint8_t scratch[iotspool_required_scratch_bytes(&cfg)];

iotspool_init_inplace(&spool, entries, 64,
                      scratch, sizeof(scratch),
                      &cfg, &store);

大小可以用 iotspool_required_index_bytes(&cfg) 和 iotspool_required_scratch_bytes(&cfg) 在编译期或启动时精确计算，避免多分配。

适用边界

iotspool 只负责"把 publish 消息可靠地送到 MQTT 客户端手里"，不做以下事情：

• 不做 MQTT 协议本身。连接、保活、重连、TLS、订阅都由你现有的 MQTT 栈负责。
• 不做加密。CRC32/SHA-256 只检测意外损坏，不防篡改；需要机密性请用文件系统级加密或在 payload 层加密。
• 不做 QoS 2。只保证 QoS 1 at-least-once，重复消息去重在 Broker 或业务层。
• 不跨设备同步。日志文件是单设备本地的。

如果你的设备需要"断网时数据不丢、上电自动续传、Broker 抖动不雪崩"这几件事，这个库刚好是那层缺的组件。

声明： loxdb 是一个开源项目，作者为 Vanderhell；FlashDB 是一个开源项目，作者为 Armink。本文是阅读两个项目源码并在本地完成资源实测后整理的学习笔记，用于理解嵌入式数据库的资源消耗与设计取舍。本文作者不是这两个项目的开发者，未参与任何代码贡献。 文中工程细节与测量数据来自开源代码分析与本地编译结果，不代表项目作者的设计决策。

项目仓库：github.com/Vanderhell/loxdb（可预测内存的三引擎嵌入式数据库）；github.com/armink/FlashDB（RT-Thread 生态的极简 KV/TS 数据库）

loxdb 与 FlashDB 都是面向 MCU 的嵌入式数据库。实测（Cortex-M4，-Os，链接裁剪）下，FlashDB 的 KV+TS 占 10.5KB Flash、RAM 约 1KB；loxdb 同功能占 16.7KB，全功能（KV+TS+关系型+WAL）24.3KB，RAM 最少 8.2KB 句柄加可配 arena。loxdb 用多出的 Flash 换 TTL 过期、事务、关系引擎、写入前预检和可观测的崩溃恢复；FlashDB 用极简换来资源效率与多年量产验证。RAM 预算紧张、只需配置存储时选 FlashDB，需要多引擎与可诊断性时选 loxdb。

loxdb 用资源换来的能力

两类库的资源差距来自存储架构。FlashDB 把状态写进 Flash 按需扫描，换取约 1KB 的总 RAM；loxdb 把状态放进预分配 RAM，Flash 只做持久化快照，代价是句柄与 arena 的固定占用。

loxdb 的回报集中在写入前就能感知的五项能力：

• 写入前预检：lox_preflight() 在初始化前验证配置与存储几何，lox_admit_kv_set() 在写入前返回本次操作是否会失败，lox_get_pressure() 随时查询剩余容量。FlashDB 的扇区 GC 失败只能在事后通过返回值察觉，部分 API 甚至不返回错误。
• TTL 过期：lox_kv_set() 带 ttl 参数，配合 lox_kv_purge_expired() 清理。FlashDB 需要自己存时间戳、自己写扫描删除逻辑。
• 事务：lox_txn_begin() 到 lox_txn_commit() 让多个 key 的更新原子生效，断电也不破坏。FlashDB 每个 KV 独立写入，配网参数写到一半掉电会留下半新配置。
• 可观测的崩溃恢复：lox_stats() 暴露 recovery_count 与 last_recovery_status，设备经历过掉电恢复可以被记录用于售后诊断。FlashDB 的状态位翻转同样防掉电，但不会上报恢复事件。
• 关系型引擎与迁移：schema 建表、索引列、lox_rel_find_by() 按列查找；schema 带版本号，on_migrate 回调处理固件升级时的结构变更。FlashDB 只有 KV 默认值升级，解决不了表结构变化。

资源占用实测

以下数字来自 arm-none-eabi-gcc 14.3.1 对 Cortex-M4 的 -Os 编译，链接时开启 --gc-sections 裁剪。loxdb 使用官方默认配置（64 键、8 条 TS 流、4 张表）；FlashDB 数字包含其仓库自带的 FAL 抽象层（单独编译约 2.3KB），loxdb 不含存储移植层。数字用于说明资源量级，不代表所有芯片和工具链都会得到相同结果。

静态 RAM 的构成差异更大：

能力对比

选型依据

• RAM 预算 ≥ 32KB，需要多引擎、事务、TTL 或结构化查询，看重运行时可诊断，选 loxdb。
• 8~16KB RAM，只需 KV 配置存储，量产验证优先，选 FlashDB。
• 折中路径：loxdb 支持编译期裁剪（可单独关闭 TS/REL/WAL），KV-only 档约 11KB，仍高于 FlashDB 的 8.4KB。
• 建议按自己的芯片与工具链重测一次。方法可复现：arm-none-eabi-gcc -Os -ffunction-sections -fdata-sections 编译，链接加 --gc-sections，用 arm-none-eabi-size 读 section 尺寸。

loxdb 的工程化优势（预检、自检、统计、可观测恢复）建立在 8KB 以上的 RAM 契约上，这条契约在小内存 MCU 上不成立。选型依据是 RAM 预算落在哪一档；预算允许时，功能清单才参与比较。

声明： loxseq 是一个开源项目，作者为 Vanderhell。本文是阅读该项目源码和文档后整理的学习笔记，用于理解嵌入式掉电恢复状态机的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/loxseq（断电恢复状态机的 C 语言参考实现）

概述

嵌入式设备经常跑多步流程：灌装、加热、排空，或者充电、标定。任何一步执行中掉电、看门狗复位或 OTA 重启，设备就忘了自己干到哪一步。重做的代价有三种形态：重复执行会破坏（投料、加药、校准），会危险（加热中重启再加热可能过温），会浪费（小时级流程从头再来）。

解决办法是一套设计思想：把进度以检查点形式持久化，重启后读回检查点，按每步预设的恢复策略决定续跑、重跑、放弃还是问人。检查点不只是一个步骤号：写入可能只完成一半（撕裂写），固件升级后步骤表会变，旧记录可能比新的更新，这些都要靠校验、版本、指纹等附加信息兜住。本文以开源项目 loxseq 作为这套思想的参考实现展开，重点在思想本身。这个库的适用面很窄，后面会说明。

恢复策略按步骤声明

"断电后怎么办"没有统一答案，同一流程里每步都不一样。把策略声明在步骤表里，执行交给状态机：

举例：灌装可以续（液位到设定值即可），加热可以续（温度到设定值即可），加药绝不恢复（药不能加两次），排空要问人（罐里有什么只有操作员知道）。策略按步声明，机器只执行裁决，人工闸门留在该留的地方。

最小集成示例

以 loxseq 为例看这套思想怎么落地：三步接入。

步骤表

每步声明标签、动作、超时和恢复策略。动作返回 LOXSEQ_STEP_RUNNING 表示进行中，返回 LOXSEQ_STEP_DONE 表示完成。

enum { S_FILL, S_HEAT, S_DRAIN, STEP_COUNT };

static loxseq_step_status_t step_fill(loxseq_t *s, uint32_t now_ms, void *u) {
    (void)u;
    if (loxseq_step_age_ms(s, now_ms) >= 2000) return LOXSEQ_STEP_DONE;
    return LOXSEQ_STEP_RUNNING;
}
/* step_heat、step_drain 结构相同，此处省略 */

static const loxseq_step_def_t steps[STEP_COUNT] = {
    [S_FILL]  = { .tag = "fill",  .action = step_fill,
                  .timeout_ms = 30000,
                  .resume_policy = LOXSEQ_RESUME_AT_STEP },
    [S_HEAT]  = { .tag = "heat",  .action = step_heat,
                  .timeout_ms = 30000,
                  .resume_policy = LOXSEQ_RESUME_AT_STEP },
    [S_DRAIN] = { .tag = "drain", .action = step_drain,
                  .timeout_ms = 30000,
                  .resume_policy = LOXSEQ_NEVER_RESUME },
};

存储钩子

实现写、读、擦三个回调。后端持久化序列化后的 32 字节检查点，不保存 C 结构体的内存映像。

static const loxseq_storage_t storage = {
    .write_checkpoint = my_flash_write,  /* 持久化 32 字节检查点 */
    .read_checkpoint  = my_flash_read,
    .erase_checkpoint = my_flash_erase,  /* 擦除后表现为冷启动 */
};

开机流程

开机先 loxseq_recover() 得出裁决，再按裁决启动；主循环周期性调用 loxseq_tick() 驱动步骤执行。

static loxseq_err_t my_safe_init(loxseq_t *s, uint32_t t, void *u) {
    (void)s; (void)t; (void)u; return LOXSEQ_OK; /* 安全初始化，示例为空实现 */
}
static const loxseq_safe_init_t safe_init_cfg = { .run = my_safe_init, .user = NULL };

loxseq_t seq;
loxseq_init(&seq, steps, STEP_COUNT, &storage, &safe_init_cfg);

loxseq_recovery_verdict_t v = loxseq_recover(&seq, LOXSEQ_REBOOT_NORMAL);
switch (v) {
    case LOXSEQ_RECOVERY_COLD_START: loxseq_start_fresh(&seq, now_ms);     break;
    case LOXSEQ_RECOVERY_RESUME:     loxseq_start_resume(&seq, now_ms);    break;
    case LOXSEQ_RECOVERY_RESTART:    loxseq_start_restart(&seq, now_ms);   break;
    case LOXSEQ_RECOVERY_SAFE_INIT:  loxseq_start_safe_init(&seq, now_ms); break;
    case LOXSEQ_RECOVERY_OPERATOR:   loxseq_start_operator_wait(&seq);     break;
}

while (1) {
    loxseq_tick(&seq, now_ms());   /* 每步的动作在这里被调用 */
}

运行中分支

默认流程单向推进。需要按业务条件跳转时，动作里先调 loxseq_set_next_step() 设目标，再返回 LOXSEQ_STEP_BRANCH。以质检步骤为例：合格跳去打包，不合格先跳去重工。跳转目标不限相邻；返回 BRANCH 却没设目标会让序列器进入 FAILED。

完整可编译示例（含打印步骤顺序的 main）：下载分支示例

场景约束

这套设计有三个明确的禁区，loxseq 的文档也写明了：

1. 涉及生命安全的场景。loxseq 自己声明不提供安全等级：无 SIL 认证、无 IEC 61511、无 ISO 26262。检查点只记录软件知道的进度，不记录液位、温度、位置这些物理事实；断电期间物理过程还在演化，恢复时世界已经变了。安全场景的恢复必须止步于安全状态并等人工确认，自动续跑是错误设计。
2. 重大财产损失场景。恢复策略不可证明安全时，机器替人做决定就是风险。
3. 生产现场的主控。工厂工艺层的主控是 PLC/DCS 加安全 PLC，联锁、报警、配方都在那一层，断电恢复非常保守。检查点恢复适合的是设备内部的序列（点胶机归零分装、电池充电阶段、打印机断电续打），位置在 PLC 之下，两者叠加使用，互不替代。

另外要说明的是：这个库的适用面很窄，没有公开的采用记录，项目作者也举不出确切的用户。把它当作高质量的参考实现来阅读更合适，价值在思想，不在这份代码。

需要检查点恢复的四个特征

用不用这套设计，判断标准是"重做代价"，与断电概率无关。四个特征命中其一就值得考虑：

1. 流程里有一次性或不可逆步骤，重复执行会破坏物料或设备。
2. 单步分钟到小时级，重跑代价大。
3. 断电后"知道刚才在干什么"本身就是安全条件（加热中、均衡中）。
4. 重启源多样：看门狗、OTA、电池耗尽、用户关机。

四个特征全不命中，重启后从头跑一遍没损失，就不需要这套设计。大多数项目属于这一类，自己写几十行状态机比引入依赖更划算。

即便不采用检查点恢复，这套思想里的几个设计点值得带走：恢复策略按步声明、终结写墓碑防止重做、步骤表指纹防固件升级误恢复、数据可疑时保守降级、时钟驱动状态机可测可移植。

声明： lwevt 是一个开源项目，作者为 Tilen MAJERLE。本文是阅读该项目源码和文档后整理的学习笔记，用于理解 X-macro 类型生成与广播分发在嵌入式事件系统里的实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/MaJerle/lwevt

这篇文章讲 lwevt 源码里的三个实现思想：类型系统交给编译器生成、分发退化成一次数组遍历、状态只有三个静态变量。

核心思想

lwevt 把整个事件系统压到最小：170 B 代码加 48 B RAM。三个落点：

• 类型用 X-macro 生成：声明一次，枚举和 union 同时出来
• 分发用广播：所有监听器收所有事件，过滤下沉到监听器
• 状态用全局单例：一个静态句柄、一个静态监听表、一个计数，无堆无锁

X-macro：两次 include 生成类型系统

X-macro 的核心技巧：宏在 include 之前重新定义，让同一个头文件在两次 include 时展开成不同内容。

lwevt_type.h 先给两个宏提供空默认值，再 include 用户的 lwevt_types.h，最后 undef：

#ifndef LWEVT_TYPE_BASIC
#define LWEVT_TYPE_BASIC(name)
#endif
#ifndef LWEVT_TYPE_EXT
#define LWEVT_TYPE_EXT(name, data)
#endif
#include "lwevt_types.h"   /* 用户的事件声明 */
#undef LWEVT_TYPE_BASIC
#undef LWEVT_TYPE_EXT

lwevt.h 第一次 include 前把宏定义成生成枚举成员，第二次定义成生成 union 成员：

/* 第一次：枚举 */
#define LWEVT_TYPE_BASIC(name)   name,
#define LWEVT_TYPE_EXT(name, data) name,
#include "lwevt/lwevt_type.h"

/* 第二次：union */
#define LWEVT_TYPE_EXT(name, data) data;
#include "lwevt/lwevt_type.h"

用户在 lwevt_types.h 里只写一行声明：

LWEVT_TYPE_EXT(LWEVT_TYPE_TEMP_READY, struct { int16_t temp_x10; } temp)

编译后同时得到枚举成员 LWEVT_TYPE_TEMP_READY 和 union 成员 temp，类型与数据绑定，改一处两端生效。

广播分发：一次遍历调用全部监听器

lwevt_dispatch_ex 只有两个动作：

1. evt_handle->type = type
2. for (idx = 0; idx < evt_fncs_cnt; ++idx) evt_fncs[idx](evt_handle)

没有话题过滤，没有匹配逻辑。每个监听器收到每个事件，自己用 switch 或 if 判断 type。数据零拷贝：事件数据就在句柄的 union 里，监听器直接读写。

注册去重与全局单例

• lwevt_register 先遍历现有监听表查重，同一个函数指针直接返回 0，避免重复注册后每个事件触发两次
• 状态是三个 static：默认句柄 evt、监听表 evt_fncs[8]、计数 evt_fncs_cnt。LWEVT_CFG_ENABLE_DEFAULT_HANDLE=0 时去掉默认句柄，改用 lwevt_dispatch_ex 传自己的句柄，再省 12 B
• 没有退订接口：数组只追加不删除，这是把接口压到最小的取舍

设计取舍与边界

• 广播换简单：遍历没有匹配开销，代价是每个监听器都要处理无关事件
• 类型生成换手感：X-macro 让事件声明集中在一处，代价是读代码要先理解宏展开
• 单例换零成本：无堆无锁，代价是只能有一套监听表、无法退订
• 边界：dispatch 同步执行，在中断里调用时回调也在中断上下文运行

声明： LwEVT 是一个开源项目，作者为 Tilen MAJERLE。本文是阅读该项目源码和文档后整理的入门笔记。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 示例代码已在本机 GCC 与 ARM GCC 下编译运行验证。

项目仓库：github.com/MaJerle/LwEVT

这篇文章帮你完成一件事：把 LwEVT 跑起来，实现"按键按下发一个事件、温度采集完发一个带数据的事件"。全程只用 5 个 API，不需要理解内部实现。

LwEVT 的调用流程

LwEVT 是事件分发器：事件（event）由类型 type 区分，监听器（listener）就是普通回调函数。核心动作只有两个：

1. LwEVT_register() 注册回调，可注册多个，最多 LwEVT_CFG_MAX_EVT_LISTENERS 个（默认 8）
2. LwEVT_dispatch() 广播事件给所有已注册回调，逐个调用

示例代码：按键与温度事件

先建两个文件：LwEVT_opts.h（配置）和 LwEVT_types.h（事件类型），从仓库的 LwEVT_opts_template.h、LwEVT_types_template.h 复制改名即可。

LwEVT_types.h 定义事件类型。LwEVT_TYPE_BASIC 定义不带数据的事件，LwEVT_TYPE_EXT 定义带数据的事件，数据声明成 C 结构体：

LwEVT_TYPE_BASIC(LwEVT_TYPE_BTN_PRESSED)
LwEVT_TYPE_BASIC(LwEVT_TYPE_BTN_RELEASED)
LwEVT_TYPE_EXT(LwEVT_TYPE_TEMP_READY, struct { int16_t temp_x10; } temp)

main.c 完整流程：

#include "LwEVT/LwEVT.h"
#include <stdint.h>

static uint32_t btn_press_count;

/* 监听器 1：按键计数 + 温度判断 */
static void on_event(LwEVT_t *evt)
{
    switch (evt->type) {
    case LwEVT_TYPE_BTN_PRESSED:
        btn_press_count++;
        break;
    case LwEVT_TYPE_TEMP_READY:
        /* 零拷贝：直接读句柄 union 里的数据 */
        if (evt->msg.temp.temp_x10 > 300) {
            /* 超过 30.0 °C */
        }
        break;
    default:
        break;
    }
}

/* 监听器 2：只关心温度，独立记录 */
static void on_temp_log(LwEVT_t *evt)
{
    if (evt->type == LwEVT_TYPE_TEMP_READY) {
        /* 把温度写入日志缓冲区 */
    }
}

int main(void)
{
    LwEVT_t *evt;

    LwEVT_init();                 /* 1. 初始化 */
    LwEVT_register(on_event);     /* 2. 注册监听器 1 */
    LwEVT_register(on_temp_log);  /* 3. 注册监听器 2 */

    /* 4. 无数据事件：直接 dispatch */
    LwEVT_dispatch(LwEVT_TYPE_BTN_PRESSED);

    /* 5. 带数据事件：先拿句柄写数据，再 dispatch */
    evt = LwEVT_get_handle();
    evt->msg.temp.temp_x10 = 315;
    LwEVT_dispatch(LwEVT_TYPE_TEMP_READY);

    return 0;
}

运行输出（验证版加 printf）：

button pressed, count=1
temp=31.5 C
over 30.0 C
temp logged=315

关键点：dispatch 是广播，所有已注册监听器都会收到每个事件（上例两个监听器各处理一次）；监听器自己判断关心哪种事件（用 switch 或 if）。注册顺序就是调用顺序，同一函数指针重复注册会被去重。

LwEVT_opts.h 配置项

• LwEVT_CFG_MAX_EVT_LISTENERS：监听器上限，默认 8
• LwEVT_CFG_ENABLE_DEFAULT_HANDLE：默认句柄开关，默认 1；置 0 时改用 LwEVT_dispatch_ex(&evt, type) 传自己的句柄

LwEVT 的特色

• 极小：库代码约 170 B（Cortex-M4，-Os），静态 RAM 48 B
• X-macro 类型系统：事件类型和携带数据在编译期生成，改类型只动 LwEVT_types.h
• 零拷贝：监听器直接读写句柄里的数据
• API 只有 5 个函数，注册自动去重

适用边界

• 全局单例：整个程序只有一套监听表，无法创建多个独立的事件系统
• 无法退订：注册后不能移除回调
• 无队列：dispatch 同步执行全部回调，在中断里调用时回调也在中断上下文运行

声明： MCU-Malloc-Tracker 是一个开源项目，作者为 Vanderhell（项目仓库）。本文是阅读该项目源码和文档后整理的学习笔记，用于理解 MCU 堆内存追踪的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/MCU-Malloc-Tracker（面向裸机 MCU 的 malloc/free 追踪库，查泄漏、找分配热点、导出崩溃快照）

malloc 是从堆里动态申请内存的标准接口，配套的 free 负责归还。MCU 上的动态内存很有限，用错一点，问题要跑几天才暴露。

场景：设备随机崩溃，泄漏查不到

最常见的故障链条：某模块反复 malloc 却忘记 free，堆被悄悄吃光，之后某次分配失败，或者写穿边界，系统随机复位。排查的难点在现场留不住：设备不能随便接仿真器，故障后自动复位，等连上调试器时堆的状态已经没了。

这个库的思路是平时就把堆的账记下来：谁在哪个文件第几行分配了多大一块，分配顺序如何。出了事翻账本，泄漏点、分配热点、崩溃时的堆现场全部可查。

拦截：宏替换把 malloc 换成记账版

要拦下每一次 malloc，用的是 C 预处理器宏替换：

#define malloc(x) mt_malloc((x), __FILE__, __LINE__)

代码里的 malloc(256) 在编译期变成 mt_malloc(256, "driver.c", 42)，文件路径和行号由编译器自动填好，业务代码一行不用改。库内部先调真实分配器拿到指针，再写一条记录。

宏拦截最怕递归：mt_malloc 内部调用真实 malloc，真实分配器若再触发宏展开，就会无限嵌套。库用一个 g_inside 标志做递归保护，进入追踪逻辑时置位，置位状态下直接放行到真实分配器。

账本：静态哈希表记下每次分配

记账表是一张静态数组，容量编译期固定（默认 512 项，必须是 2 的幂）。定位槽位用指针哈希：idx = hash(ptr) & (N-1)。用位与代替取模，MCU 上省掉除法开销，分配和释放都是平均 O(1)。每条记录包含指针、大小、文件哈希、行号、序号五样信息。

释放时不能把记录直接清空。哈希表靠连续探测找槽位，清空会打断探测链，后面的分配可能找不到。库把释放的槽位标记成墓碑（tombstone）：查找时跳过，下次插入优先复用，代价是探测距离缓慢变长。表满时采用丢记录策略，真实分配照常成功，只是不记账，损失由 table_drops 计数如实暴露。

快照：确定性二进制带回 PC 解码

MCU 上通常没有可靠时钟，库不用时间戳，改用单调递增的序号记录分配顺序。同一段分配序列必然产生同一个内部状态，快照逐字节可复现，方便对比和回归验证。

mt_snapshot_write() 把当前所有存活记录导出成 MTS1 二进制：36 字节头加每条 24 字节记录，记录按指针升序排序，CRC32/IEEE 覆盖整份数据。文件名不存字符串，存 FNV1a-32 哈希，快照体积小、跨编译稳定；PC 端解码时用 --filemap 把哈希映射回源码路径。仓库自带的 demo 在本地编译运行后，解码器输出的 CRC 校验通过。

三条设计底线：确定性、零 malloc、诚实

三条底线互相支撑：追踪器不申请内存，才有固定可预测的开销，能在任何 MCU 上稳定跑；状态完全确定，快照才可比对。碎片率是最典型的诚实案例：没有平台堆遍历钩子时，库直接报告 N/A；想要真实值，自己实现两个平台钩子即可，库只负责展示。

适用边界

• 活跃分配数超过表容量时丢记录，默认 512 项，table_drops 可查。
• ISR 里调用 malloc 时，需要自己定义 MT_LOCK / MT_UNLOCK（例如关中断）。
• FILE 路径跨编译不稳定时，用 -fmacro-prefix-map 固定前缀，保证文件哈希能映射回源码。

声明： microbus 是一个开源项目，作者为 Peter Vanderhell。本文是阅读该项目源码和文档后整理的学习笔记，用于理解嵌入式事件总线在裸机上的确定性实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/microbus

这篇文章讲 microbus 源码里的三个实现思想：状态归调用者、分发确定性优先、队列用快照保证有界。不重复入门用法，直接看机制。

核心思想

microbus 的全部设计围绕一个目标：在单上下文裸机上提供确定性的发布订阅。三个落点：

• 状态归调用者：mbus_t 由调用者分配，库内没有全局变量，可多实例、可放栈上
• 分发确定性：遍历订阅表按固定顺序，分发期间锁定订阅表
• 队列有界性：dispatch 入口快照队列计数，单次分发绝不失控

订阅表与投递期锁定

订阅表就是 mbus_t 里的 subs[16] 数组，每个槽是 {topic, handler, ctx, active}。分发时 mbus_deliver 从下标 0 升序扫到 MBUS_MAX_SUBSCRIBERS，话题匹配或命中 MBUS_TOPIC_ANY 就调用回调。

确定性从哪来：mbus_deliver 进出时维护 delivery_depth 计数。深度大于 0 期间，subscribe、unsubscribe、unsubscribe_topic 直接返回 MBUS_ERR_BUSY。效果是分发期间订阅表不可变，遍历顺序和结果都可预测。代价是回调里不能改订阅，只能等分发结束再改。

环形队列的单调计数

队列是 queue[8] 加 q_head、q_tail，两个 32 位计数器只增不减，用 (head & (DEPTH-1)) 取模定位槽位，所以深度必须是 2 的幂。满判定是 head - tail >= DEPTH，空判定是 head == tail。

单调计数的好处：不需要单独的 count 字段；32 位计数要入队 2^32 次才回绕；单生产者单消费者下 head 和 tail 各自只被一方写，配合临界区宏就能构成 ISR 与主循环的通道。

dispatch 入口快照

队列存在的意义是解耦产生事件和处理事件。mbus_dispatch 的实现思想是快照：

1. 入口取 eligible = 当前队列计数
2. 循环最多处理 eligible 个：pop 到局部事件，分发，eligible--
3. 回调里再入队的事件本回合不处理，留到下次 dispatch

没有快照的版本，回调再入队会让循环追着队尾跑，可能无限执行。快照把单次 dispatch 的执行时间变成有界：最多 eligible 次回调，回调里入队再多也只增长 head。

ABI 校验与统计计数

• mbus_impl_init 校验 bus_size == sizeof(*bus)：库和消费者配置不一致时编译出不同大小的结构，运行期直接拒绝，避免踩坏调用者内存
• publish_count、deliver_count、drop_count 三个计数器，drop 记录队列满丢事件，丢事件率可观测
• MBUS_ISR_SAFE_QUEUE 开启时 push、pop、计数都用临界区宏包裹，构成 SPSC 模式

设计取舍与边界

• 拷贝换安全：payload 拷进事件对象，调用方缓冲可复用，代价是 40 B 事件对象加一次 memcpy
• 确定性换灵活：分发期锁定订阅表，回调内改订阅被拒绝
• 有界换吞吐：单次 dispatch 只处理入口快照，回调密集入队时事件延迟到下次
• 边界：默认单上下文，多线程访问要外部加锁；话题空间 uint8 只有 256 个

声明： MicroBus 是一个开源项目，作者为 Peter Vanderhell。本文是阅读该项目源码和文档后整理的入门笔记。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 示例代码已在本机 GCC 与 ARM GCC 下编译运行验证。

项目仓库：github.com/Vanderhell/MicroBus

这篇文章帮你完成一件事：把 MicroBus 跑起来，实现"传感器模块发布电压读数，多个模块按话题订阅接收"。核心概念只有两个：话题（topic，事件的类别）和订阅（subscribe，声明自己关心哪个话题）。事件携带的数据叫 payload（载荷）。

MicroBus 的调用流程

1. mbus_init() 初始化总线
2. mbus_subscribe() 按话题注册回调
3. mbus_publish() 发布事件，同步调用话题匹配的回调

示例代码：传感器读数广播

mbus.h 自带默认配置（16 个订阅槽、32 字节 payload、8 深度队列），直接包含就能用：

#include "mbus.h"
#include <stdint.h>
#include <string.h>

static uint16_t g_last_mv;

static void on_sensor(const mbus_event_t *event, void *ctx)
{
    (void)ctx;
    if (event->payload_len != sizeof(uint16_t)) {
        return;
    }
    memcpy(&g_last_mv, event->payload, sizeof(g_last_mv));
}

static void on_any(const mbus_event_t *event, void *ctx)
{
    (void)event;
    (void)ctx;
}

int main(void)
{
    mbus_t bus;
    uint16_t mv = 3300;

    mbus_init(&bus, NULL);            /* 1. 初始化，时钟可传 NULL */

    /* 2. 订阅：on_sensor 只收 MBUS_TOPIC_SENSOR，on_any 收所有话题 */
    mbus_subscribe(&bus, MBUS_TOPIC_SENSOR, on_sensor, NULL);
    mbus_subscribe(&bus, MBUS_TOPIC_ANY, on_any, NULL);

    /* 3. 立即发布：同步调用回调 */
    mbus_publish(&bus, MBUS_TOPIC_SENSOR, &mv, sizeof(mv));

    /* 4. 入队延后分发：先攒事件，主循环统一 dispatch */
    mbus_queue(&bus, MBUS_TOPIC_SENSOR, &mv, sizeof(mv));
    mbus_queue_signal(&bus, MBUS_TOPIC_BOOT);
    mbus_dispatch(&bus);

    return 0;
}

运行输出（验证版加 printf）：

sensor: 3300 mV
any event received, count=1
sensor: 3300 mV
any event received, count=2
any event received, count=3

publish 立即触发 on_sensor 和 on_any 各一次；队列里的两个事件在 dispatch 时各触发一次，MBUS_TOPIC_BOOT 不带数据所以只有 on_any 收到。

mbus_config.h 配置项

• MBUS_MAX_SUBSCRIBERS：订阅槽数量，默认 16
• MBUS_MAX_PAYLOAD：payload 上限，默认 32 字节
• MBUS_ENABLE_QUEUE：队列开关，默认 1
• MBUS_QUEUE_DEPTH：队列深度，默认 8，必须是 2 的幂
• MBUS_ISR_SAFE_QUEUE：ISR 安全模式，默认 0；开启需提供临界区宏

MicroBus 的特色

• 话题过滤：订阅时指定话题，回调只收到匹配事件；MBUS_TOPIC_ANY 通配
• payload 拷贝进事件对象，调用方的临时缓冲可以立刻复用
• 有界队列：ISR 里 mbus_queue 入队，主循环 mbus_dispatch 统一处理
• 确定性：分发期间修改订阅表返回 MBUS_ERR_BUSY
• 调用者持有状态：mbus_t 放栈或静态，可多实例

适用边界

• 默认单上下文，多线程访问需要外部加锁
• 话题空间 256 个，payload_len 单字节上限 255
• mbus_t 约 544 B RAM（16 订阅槽 + 8 队列，Cortex-M4），放栈上要确认栈空间足够

声明： microbus 与 LwEVT 都是开源项目。microbus 的作者是 Peter Vanderhell，LwEVT 的作者是 Tilen MAJERLE。本文是对两个项目源码做 ARM GCC 编译与资源实测后整理的对比笔记。本文作者不是这些项目的开发者，未参与任何代码贡献。 文中资源数据来自编译实测，工程细节来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：

• microbus：github.com/Vanderhell/microbus，话题事件总线
• LwEVT：github.com/MaJerle/LwEVT，极简事件分发器

结论

两个库都无需堆分配，可直接集成进 Cortex-M 工程。LwEVT 用 170 B 代码和 48 B RAM 完成广播分发：注册回调后 dispatch 逐个调用，携带数据的类型由 X-macro 在编译期生成。microbus 用 972 B 代码和 544 B RAM 提供完整事件总线：话题过滤、通配订阅、payload 拷贝、有界队列、确定性分发、错误码与 ABI 校验。资源差距来自功能差距，两者都在各自定位内把代价花在该花的地方。选型看需求：只要求通知一组回调、偶尔带点数据，LwEVT 够用；需要话题路由、ISR 入队、多实例或错误诊断，选 microbus。

两库结构对比如下：microbus 把订阅表和环形队列放进调用者持有的 mbus_t，按话题过滤分发；LwEVT 用全局静态监听表做广播，监听器自行按 type 过滤。

资源占用对比（Cortex-M4 实测）

工具链 arm-none-eabi-gcc 14.3.1，Cortex-M4，-Os，链接 --gc-sections；完整程序为库加对等功能测试程序加 crt0。两库均通过 -Wall -Wextra -Werror 零告警。

关键解读：microbus 的 544 B RAM 由调用者决定占用位置，放栈或静态都行，关掉队列再省约 328 B；LwEVT 的 48 B 是编译进去就固定的全局量，关默认句柄可降到 36 B。

microbus 的设计收益

• 实例化设计：mbus_t 由调用者持有，可多实例、放栈上，测试隔离容易
• 话题过滤：uint8 话题加 MBUS_TOPIC_ANY 通配订阅，回调只收到匹配事件
• payload 拷贝进事件对象，调用方的临时缓冲可以立刻复用
• 有界队列：环形缓冲、深度为 2 的幂；mbus_dispatch 入口快照队列长度，回调里再入队不会让本次分发无限执行
• 确定性：投递期间修改订阅表返回 MBUS_ERR_BUSY，升序遍历保证顺序
• 错误契约：8 个错误码加 mbus_err_str()；mbus_impl_init 用 sizeof(*bus) 校验 ABI
• 可裁剪：关队列省约 328 B RAM，MBUS_ISR_SAFE_QUEUE 模式配临界区钩子支持 ISR 入队

LwEVT 的设计收益

• X-macro 类型系统：在 LwEVT_types.h 声明 LwEVT_TYPE_BASIC / LwEVT_TYPE_EXT，编译期生成枚举和数据 union，事件类型与携带数据绑定
• 零拷贝：监听器直接读写句柄里的 union，不复制 payload
• API 只有 5 个函数，注册自动去重
• 可关默认句柄再省 12 B
• 代价：全局单例、无法退订、无队列、错误只回 0/1、无并发保护

选型依据

• 场景 A：Flash 只剩几百字节，只做简单事件广播，选 LwEVT。170 B 代码加 48 B RAM，接近免费。
• 场景 B：需要话题过滤、ISR 入队延迟处理、多实例或错误诊断，选 microbus。972 B 代码，RAM 按需实例化。
• 判断句：能接受所有监听器收所有事件、自行按 type 过滤，LwEVT 够用；出现只关心某类话题、或中断里发事件主循环处理的需求，就换 microbus。
• 边界：LwEVT 无法退订是实际限制；microbus 的话题空间只有 256 个、payload_len 是单字节，都是容量上限。

声明： microcbor 是一个开源项目，作者为 Vanderhell。本文是阅读该项目源码和文档后整理的学习笔记，用于理解嵌入式场景下 CBOR 编解码的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/microcbor（单文件 C99 实现，~500 行）

配套入门篇：microcbor 入门：MCU 上用 CBOR 编码遥测消息

CBOR 线格式基础

CBOR 把每一项编码成「头 + 可选负载」。头字节的高 3 位是 major type（大类），低 5 位是 additional info（参数长度）。microcbor 所有编解码逻辑都是围绕这个头字节展开的。

major type 与 microcbor 支持情况：

additional info 的宽度规则在 RFC 里是统一表：0–23 直接当值；24 表示后面跟 1 字节参数；25 跟 2 字节大端；26 跟 4 字节大端；27 跟 8 字节（microcbor 不处理）；31 表示不定长（microcbor 不处理）。

编码器：一次写一个头

编码端的核心是 enc_head，它根据参数大小选最短宽度，把 major type 和宽度编码写进 5 字节临时 buffer，返回实际占用的头长度：

static size_t enc_head(uint8_t major, uint32_t value, uint8_t out[5]) {
    if (value <= 23) {
        out[0] = (uint8_t)(major | (uint8_t)value);
        return 1;
    } else if (value <= 0xFF) {
        out[0] = (uint8_t)(major | CBOR_INFO_1BYTE);  /* 24 */
        out[1] = (uint8_t)value;
        return 2;
    } else if (value <= 0xFFFF) {
        out[0] = (uint8_t)(major | CBOR_INFO_2BYTE);  /* 25 */
        put_u16(out + 1, (uint16_t)value);
        return 3;
    } else {
        out[0] = (uint8_t)(major | CBOR_INFO_4BYTE);  /* 26 */
        put_u32(out + 1, value);
        return 5;
    }
}

mcbor_enc_uint 直接调用 enc_append_head_only(enc, CBOR_MAJOR_UINT, value)；mcbor_enc_int 对负数做 -1-n 转换后改用 major 1；字符串/字节串先用 enc_head(CBOR_MAJOR_TEXT, len, ...) 写长度头，再 memcpy payload；array/map 只写头，不校验后续是否真有那么多项。

这种设计的结果是：编码器是纯顺序写，没有回溯修补长度的操作（因为只支持定长容器，调用方必须在写 mcbor_enc_map(n) 前就知道有 n 对）。代价是调用方必须对结构有把握；收益是 encoder 不需要维护容器栈，代码只有 ~130 行。

宽度选择的边界

几个值得注意的宽度判断：

• value <= 23 走 1 字节头（单字节 0x00–0x17 直接表示小整数，这是 CBOR 定义的）。23 这个分界来自 RFC 本身，microcbor 并未自定义。
• 有符号整数 mcbor_enc_int 对非负数转调 uint 编码（major 0），对负数走 major 1 并把值映射为 -(value+1) 的无符号表示。-1 编码成 0x20（major 1, info=0），是最短负整数。
• float32 固定走 major 7 + info=26 + 4 字节 IEEE 754 bit pattern；库用 memcpy(&bits, &f, 4) 做 bit cast，避开 strict aliasing，并用编译期 typedef char assert[(sizeof(float)==4 && ...)?1:-1] 硬约束 float 必须是 binary32。

sticky overflow：链式编码只查一次

编码器结构体只维护 buf / capacity / pos / overflow 四个字段，其中 overflow 是 sticky bit：

static mcbor_err_t enc_prepare_write(const mcbor_enc_t *enc, size_t len) {
    if (enc->overflow) return MCBOR_ERR_OVERFLOW;
    if (enc->pos > enc->capacity) return MCBOR_ERR_INVALID;
    if (len > enc->capacity - enc->pos) {
        return MCBOR_ERR_OVERFLOW;
    }
    return MCBOR_OK;
}

一旦某次写入触发 overflow，enc_append_item 会把 enc->overflow = true 置位，后续所有写入在 enc_prepare_write 第一行就直接返回错误，不再推进 pos。这样调用方可以安全地连写一长串：

mcbor_enc_map(&enc, 4);
mcbor_enc_str(&enc, "dev");   mcbor_enc_str(&enc, "s-01");
mcbor_enc_str(&enc, "temp");  mcbor_enc_float(&enc, 23.4f);
/* ... */
if (mcbor_enc_overflow(&enc, &ovf) != MCBOR_OK || ovf) {
    /* 整个消息放弃 */
}

不用每次都检查返回值，也不会因为中间某次溢出导致 pos 越界写内存。这是典型的"记录错误、继续做空跑、收尾统一处理"模式，在 telemetry 这种"消息要么完整发出、要么整块丢弃"的场景里比逐次 goto fail 更实用。

另一个防御性细节是 ranges_overlap 检查：如果调用方把输出 buffer 内的某段作为 payload 传给 mcbor_enc_text/bytes，且这段区间与即将写入的位置重叠（典型出现在"边编码边用自己 buffer 里的字符串"的错误用法），enc_append_item 直接返回 MCBOR_ERR_INVALID，避免 memcpy 自覆盖产生未定义行为。

解码器：dec_next_core 一次读一个完整项

解码入口是内部的 dec_next_core，它先读 1 字节 initial byte，拆出 major/info，再通过 dec_argument 按 info 宽度读取参数（整数 argument 或长度），然后按 major 分发：

• uint/negint：直接把 argument 填进 val.val.uint_val / int_val（negint 做 -1-argument 转换并检查 argument > INT32_MAX 防越界）。
• bytes/text：先 dec_require_bytes(dec, argument) 校验剩余字节够，text 额外走 is_valid_utf8，然后把 val.val.bytes.ptr 指向输入 buffer 里这段起始位置，pos 前移长度。这就是 mcbor_dec_bytes_ref 零拷贝的来源：它不复制数据，只返回指针。
• array/map：只把 count 填到 val.val.container，不递归，也不校验后面有没有那么多项。
• simple（major 7）：info 20/21/22 对应 false/null/true 单字节；info=26 读 4 字节 float bit pattern；其余返回 invalid。

所有 typed convenience 函数（mcbor_dec_uint/float/str/...）都遵循同一个模板：先 next = *dec 局部拷贝，在副本上跑 dec_next_core，成功了才 *dec = next 提交读指针。失败时 dec 状态保持不变，调用方可以回退或报告错误。这是 commit-or-rollback 模式，代价是一个结构体拷贝（很小），换回来的是错误路径下不会把读指针推到半中间状态。

mcbor_dec_str 和 mcbor_dec_bytes_ref 的差异体现了一个明确的责任边界：

• 文本字符串用 mcbor_dec_str，库负责拷贝到调用方 buffer 并补 \0，保证拿到的是普通 C 字符串；
• 二进制 payload 用 mcbor_dec_bytes_ref，库只返回指针和长度，不拷贝，调用方保证解码期间输入 buffer 不被释放或覆写。

迭代式 skip：不用递归跳嵌套

mcbor_dec_skip 是整个库里唯一需要处理嵌套结构的地方，实现上完全没有递归，用一个 pending 计数器做广度展开：

static mcbor_err_t dec_skip_core(mcbor_dec_t *dec) {
    size_t pending = 1;
    while (pending != 0) {
        mcbor_value_t val;
        size_t child_count = 0;
        mcbor_err_t err = dec_next_core(dec, &val);
        if (err != MCBOR_OK) return err;
        pending--;
        if (val.type == MCBOR_ARRAY) {
            child_count = val.val.container;
        } else if (val.type == MCBOR_MAP) {
            if (val.val.container > SIZE_MAX / 2) return MCBOR_ERR_RANGE;
            child_count = val.val.container * 2;
        }
        if (child_count != 0) {
            size_t remaining = dec->size - dec->pos;
            if (child_count > remaining) return MCBOR_ERR_INVALID;
            if (child_count > SIZE_MAX - pending) return MCBOR_ERR_RANGE;
            pending += child_count;
        }
    }
    return MCBOR_OK;
}

工作方式：

1. 初始 pending = 1（要跳过当前这一项）。
2. 每迭代一次读出一个完整项（dec_next_core 对 string/bytes 已经前移了 payload 指针），pending 减 1。
3. 如果这一项是 array(n)，说明后面还紧跟着 n 个直接子项，把 n 加到 pending；如果是 map(n)，后面紧跟着 2n 个项（n 个 key + n 个 value），加 2n。
4. pending 回到 0 时，整个值（包括所有嵌套）都被"读掉了"，读指针正好停在下一项之前。

两个防整数溢出的检查是必要的：val.val.container * 2 在 n 接近 SIZE_MAX/2 时会回绕，所以先判断 > SIZE_MAX/2；pending += child_count 也可能溢出，所以判断 > SIZE_MAX - pending。恶意 CBOR 报文可以把 n 设成 0xFFFFFFFF，递归实现会爆栈，这个迭代实现如果漏了检查就会 pending 回绕到 0 导致 skip 提前结束、后续解析错位。

mcbor_validate_one 的实现就是 mcbor_dec_init → mcbor_dec_skip → 检查 dec.pos == dec.size，复用 skip 做完整校验，不另写校验路径。这是个很干净的设计：skip 只要保证不漏读、不越界、不无限循环，validate 自然正确。

UTF-8 校验放在编码端

mcbor_enc_text 在写文本串之前先跑一次 is_valid_utf8，校验失败直接返回 MCBOR_ERR_INVALID；解码端 dec_next_core 对 major 3 也会再跑一次。两次校验看起来冗余，但责任不同：

• 编码端校验是让"我自己编码出的 CBOR 一定合法"，发现调用方传入了非法 UTF-8（比如二进制数据误当字符串），在源头报错。
• 解码端校验是让"从外部接收到的 CBOR 如果含非法 UTF-8 文本就拒绝"，防御对端问题。

is_valid_utf8 的实现是手写的单遍状态机，覆盖 1–4 字节序列以及 0xE0/0xED/0xF0/0xF4 这几个 lead byte 的特殊范围（拒绝 overlong 编码、UTF-16 surrogate halves、超过 U+10FFFF 的码位）。嵌入式目标库选择手写校验具有明确原因：无外部依赖、代码量固定、可在裸机上跑。

浮点位模式转换

float_to_bits / bits_to_float 用 memcpy 在 uint32_t 和 float 之间搬 4 字节，不做类型 punning。前面提到的编译期静态断言：

typedef char mcbor_float32_must_be_ieee754_binary32[
    (sizeof(float) == 4 && FLT_RADIX == 2 &&
     FLT_MANT_DIG == 24 && FLT_MAX_EXP == 128) ? 1 : -1];

它通过 <float.h> 的常量判断宿主平台的 float 为 binary32：基数 2、尾数 24 位（含隐含 1）、最大指数 128，这三个条件合起来等价于 IEEE 754 single precision。在不符合这个约束的平台（极少数嵌入式编译器有非 IEEE 浮点模式）上会直接编译报错，避免静默生成错误的 bit pattern。float16/float64 不在子集里，省掉了 half<->single 转换表和 64 位端序读写。

设计取舍：砍掉的特性与原因

结合 DESIGN.md 的说明和代码，几个裁剪决策是连贯的：

• 不定长：需要在数据流里打 "break" 标记，decoder 要维护一个"读到哪个容器的 break"栈，显著增大代码。遥测消息长度在编码时一定已知。
• 64 位整数：8 字节参数会让所有 uint32_t argument 局部变量升级成 64 位，在 Cortex-M0 这类 32 位核上产生软件模拟运算；传感器值、时间戳（到 2106 年的秒数都在 2^32 内）极少需要 64 位。
• Tag：给值加语义注解（比如"这是个日期"、"这是个正 bignum"），但通信双方一般有预定义 schema，Tag 只是在 wire 上多加 1–2 字节。
• 半精度/双精度：float16 需要转换表，float64 加大 payload 并把所有 bit cast 升级成 64 位；遥测里 float32 足够。

这些裁剪共同把实现压到单文件 ~500 行，且保证每条 API 的栈用量都是常数（skip 用迭代、encode 无递归、decode 无递归），对极小 RAM 的 MCU 友好。

适用边界回顾

理解内部实现之后，几个使用边界就有明确原因：

• 必须提前知道 map/array 元素数，encoder 不回填长度。
• 解码字符串默认拷贝，解码字节串零拷贝；想零拷贝处理文本需用 mcbor_dec_next 拿 val.val.bytes.ptr，返回的是未补 NUL 的原始切片。
• 输入 buffer 必须在解码期间保持有效，bytes_ref 返回的是内部指针。
• 编码输出非 canonical/deterministic CBOR：map key 顺序、整数宽度按调用方传入原样写入，不适合需要哈希签名的场景。
• float 端序是按 memcpy 出来的 bit pattern 走大端写出，要求平台是 IEEE 754 binary32（断言保证）。

入门篇里那个 demo 跑通之后，回头看这几个机制，就能判断什么时候该用 microcbor、什么时候需要换 Nanopb/cn-cbor 这类更完整的实现。

声明： microcbor 是一个开源项目，作者为 Vanderhell。本文是阅读该项目源码和文档后整理的学习笔记，用于理解嵌入式场景下 CBOR 编解码的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Vanderhell/microcbor（C99、零依赖、零堆分配的 CBOR 编解码库，面向 MCU 遥测场景裁剪了 RFC 8949 子集）

CBOR 在 MCU 遥测场景的优势

MQTT、CoAP、BLE GATT、LoRa 这几类链路传输的典型载荷是键值型遥测消息：几个传感器数值加一个设备 ID。JSON 在 PC 端是默认选项，搬到 Cortex-M0/M3 这类小 MCU 上会遇到几个具体问题：

• 每个字符串键、字符串值两端都要加引号；冒号、逗号、花括号是纯开销字节。
• 浮点数转成 ASCII 文本要走 sprintf，在无 FPU 的芯片上是最耗时的一段；数字 "23.4" 占 4 个 ASCII 字节，CBOR 里是 4 字节定长二进制 float32。
• 解析器要处理任意嵌套和字符串转义，代码体积和栈占用都偏大。

CBOR（RFC 8949）是二进制 JSON 替代品，主要思路是用一个头字节同时携带「类型 + 长度信息」，去掉所有结构标点，整数和浮点数走二进制定长编码。同一条消息通常比 JSON 短 30%–50%，在 LoRa 51 字节 payload 限制下这个差距直接决定能不能一帧发完。

microcbor 的定位

microcbor 面向遥测场景裁剪了 RFC 8949 子集，只实现：

• uint/int 32 位整数、bool、null、float32；
• UTF-8 文本串、字节串；
• 定长 array 和 map；
• 未知字段的迭代式 skip（用于前向兼容）。

砍掉的部分也是刻意的：不支持 64 位整数、不定长编码、Tag、半精度/双精度浮点。换来的是两个 .c/.h 就能集成、没有任何 malloc、编码端有 sticky overflow 标志可以连写后统一检查。

集成方式

代码只有一个实现文件和两个头文件：

• include/mcbor.h：公共 API
• include/mcbor_config.h：一个开关 MCBOR_ENABLE_FLOAT32（默认 1，关闭后 float API 返回 MCBOR_ERR_UNSUPPORTED）
• src/mcbor.c：实现

把这三个文件拷进工程，#include "mcbor.h" 即可，没有第三方依赖，C99 可编译。也可以直接用 CMake 里的 add_subdirectory 链接。

入门 Demo：编码一条传感器消息

下面这段代码编码一条 {dev:"s-01", temp:23.4, hum:55, ok:true}，验证完整性后再解回来。完整可编译文件见仓库 README 的 Quick Start，下面给出跑通的版本。

#include <stdio.h>
#include <string.h>
#include "mcbor.h"

int main(void) {
    uint8_t buf[128];
    mcbor_enc_t enc;
    size_t used = 0;

    /* 编码：4 个键值对的 map */
    mcbor_enc_init(&enc, buf, sizeof(buf));
    mcbor_enc_map(&enc, 4);
    mcbor_enc_str(&enc, "dev");   mcbor_enc_str(&enc, "s-01");
    mcbor_enc_str(&enc, "temp");  mcbor_enc_float(&enc, 23.4f);
    mcbor_enc_str(&enc, "hum");   mcbor_enc_uint(&enc, 55);
    mcbor_enc_str(&enc, "ok");    mcbor_enc_bool(&enc, true);
    mcbor_enc_size(&enc, &used);
    /* 编码后 used=30 字节，hex:
       a4 63646576 64732d3031 6474656d70 fa41bb3333
       6368756d 1837 626f6b f5 */

    /* 一次性验证：顶层 1 个完整项、无 trailing 字节 */
    mcbor_validate_one(buf, used);

    /* 解码：按 key 查表，未知 key 用 skip 跳过 */
    mcbor_dec_t dec;
    mcbor_dec_init(&dec, buf, used);

    size_t n;
    mcbor_dec_map(&dec, &n);
    for (size_t i = 0; i < n; i++) {
        char key[16]; size_t klen;
        mcbor_dec_str(&dec, key, sizeof(key), &klen);
        if (strcmp(key, "temp") == 0) {
            float v; mcbor_dec_float(&dec, &v);
            printf("temp=%.1f\n", v);
        } else if (strcmp(key, "hum") == 0) {
            uint32_t v; mcbor_dec_uint(&dec, &v);
            printf("hum=%u\n", v);
        } else if (strcmp(key, "ok") == 0) {
            bool v; mcbor_dec_bool(&dec, &v);
            printf("ok=%d\n", v);
        } else {
            mcbor_dec_skip(&dec);   /* 不识别的 key 直接跳过 value */
        }
    }
    return 0;
}

编译运行（仓库自带测试文件也用同一条命令验证过，43/43 测试通过）：

gcc -std=c99 -Iinclude src/mcbor.c demo.c -lm -o demo
./demo

几个阅读这段代码时需要注意的点：

• mcbor_enc_map(n) 只写容器头，不校验后面是否真的写了 n 对。编码器状态机不跟踪结构完整性，交给调用方或 mcbor_validate_one 收尾校验。
• 每个 mcbor_enc_* 返回 mcbor_err_t，buf 写满时会置 enc->overflow = true（sticky，置位后所有后续写入直接返回 overflow），可以在链尾用 mcbor_enc_overflow 一次检查。
• mcbor_dec_str 把文本拷进调用方提供的 buffer 并补 NUL 终止符；mcbor_dec_bytes_ref 则返回指向输入 buffer 的零拷贝指针，二进制 payload 走这个接口。
• 解码未知字段一定要用 mcbor_dec_skip，它内部是迭代式计数跳过，嵌套 array/map 也不会递归消耗栈。

API 速查

编码端（写入调用方提供的 uint8_t buf[]）：

解码端（顺序读，指针前移）：

校验：

适用边界

适合：传感器遥测、配置项导出、日志结构化字段、BLE GATT characteristic 载荷、MQTT/CoAP 短消息。

不适合：

• 载荷里需要 64 位整数、大整数、半精度/双精度浮点、Tag（比如日期 Tag 1）。
• 需要流式编码（encoder 只写定长容器头，必须提前知道元素个数）。
• 接收端需要 canonical CBOR（确定性编码）：库不排序 map key，不做最短浮点表示，NaN payload 原样出。

跑通 demo 之后，下一篇 microcbor 原理：头字节编码、sticky overflow 与迭代式 skip 展开内部实现，重点看 enc_head 宽度选择、dec_skip_core 的迭代计数、以及 UTF-8 校验放在编码端还是解码端这个取舍。

项目背景

项目原型来自本人负责的低功耗安防量产设备，安装在城市街道，设备一次性电池长效供电，依靠 IMU 震动事件唤醒 MCU，端侧完成风险研判后按需 4G 上报。

受量产项目涉密限制，搭建简化 DEMO 复现整套技术链路。设备以 50Hz 采样窗口采集 2 秒加速度时序数据，支持样本标注本地存储与网页导出；PC 端完成算法训练后，将推理逻辑以纯 C 形式部署到终端，实现本地实时分类。

整套技术可迁移至振动异常检测、故障诊断、传感器标定等工业场景。

核心工作

1. 数据采集：设定50Hz/2s采集窗口，完成IMU运动姿态时序样本采集与标注，本地SD卡存储、网页后台导出数据。
2. AutoML算法选型：基于时序数据自动遍历预处理、特征与分类算法组合，确定最优推理流水线。演示版采用轻量化简易特征；量产方案搭载全套时域、频域复合特征工程，适配复杂工业场景。
3. 算法复刻：AutoML 输出绑定特定芯片的黑盒静态库，无法跨平台运行。基于其输出的算法技术路线，借助 AI 工具逐级重建预处理、特征提取、推理全流程逻辑，经输入比对校验，复刻得到输出对齐的干净模型。
4. MCU推理优化：实现纯C无依赖算法部署，全程静态内存设计，无动态内存分配；模型体积仅3.1KB，极低资源占用，实现毫秒级端侧离线推理。
5. LVGL交互界面：基于LVGL搭建设备交互界面，实时展示三轴时序数据波形，配置姿态分类、实时推理功能按键，实现数据采集、算法推理的可视化闭环调试。

设备效果

数据采集	实时推理

A 类手势	B 类手势	C 类手势

技术路线

边缘AI 使用场景

这套"时序采集 + 特征工程 + 轻量化模型 + 纯 C 端侧部署"的骨架，是一套端侧信号处理模板，分类、回归都能覆盖，换传感器、换场景都能快速复用：

• 异常振动检测：电机、风机、泵体等旋转设备，识别轴承磨损、不平衡、松动等故障类型。
• 多传感器融合诊断：融合温度、电流、振动、声纹等多路传感器，在 MCU 本地预测设备异常并分类故障原因。
• 电弧故障检测：从电流波形中提取特征，在断路器端侧实时识别串联/并联电弧。
• 运动姿态识别：基于腕部/腰部 IMU 识别走路、跑步、跌倒、骑行等动作，应用于健康穿戴设备。
• 传感器回归标定：输入单路或多路传感器原始值，回归估算标定后的物理量，例如把气体传感器原始读数换算为浓度单位。

GitHub Demo仓库 · 演示视频

• 通讯
• • nanomodbus
• • 帧解析器 TinyFrame
• 基础设施
• • 环形缓冲区 LwRB
• • 键值对 时序数据库 loxdb(稍微重一点 11K Flash; 8K RAM) > flashDB(多数情况足够，节省37% Flash 资源，8.5K Flash; 1K RAM)
• • 轻量AB分区配置数据库 flashStore
• • 事件库 microbus(更先进，Flash 2K, RAM 872B) > LwEVT (精简，大多数情况下够用，Flash 410B, RAM 52B)
• JSON解析
• • cjson
• • LwJSON
• 内存分配器 LwMEM
• LwSHELL
• LwPRINTF
• 图形显示
• • 单色屏 U8g2
• • 彩屏 LVGL
• 边缘AI
• • TFLits
• • NanoEdgeAI

背景：MCU 通信固件收发「帧头 + 长度 + 变长数据 + 校验」私有协议帧，串口、BLE、433MHz 都按字节流到达，半帧、粘包、断包是常态。

方案：接收中断只入队不解析，中断外用逐字节状态机拆帧，失败整帧丢弃重新同步。纯 C、定长缓冲、无动态分配，裸机中断环境可用。

字节流没有消息边界

接收中断一次只拿到一个字节，通道不会告诉你帧从哪开始、到哪结束，直接当消息读全乱。解析器要自己建边界：认帧头、按长度收齐数据、核校验。字节流如何可靠到达上层，见 串口接收为什么会丢数据：从轮询到循环缓冲的改造思路，本篇只讲拆帧。

反例：凑够一帧再整体解析

按固定长度阻塞读一帧再解析，能消化半帧、粘包，但有两个硬伤：只适配定长帧（变长帧的长度在数据里，阻塞读做不到）；中间丢一个字节就整体错位，按垃圾长度永远等不齐，通道永久卡死。这不是纸上推演：某仪器厂的低功耗分析仪上位机就是固定 64 字节盲切，不找帧头、不做校验，串口丢 1 字节后帧解析永久错位，数据乱跳而软件毫无察觉，复现过程见 故障注入复现上位机丢字节失步。逐字节流式匹配则不同：丢字节只错一帧，下一帧按帧头重新对齐。

FIFO 解耦与逐字节状态机

中断里拆帧耗时不可控，中间隔一层字节流队列：中断只入队，解析器在中断外逐字节出队拆帧，解析慢不会丢字节。队列写满时的溢出策略由调用方决定：丢新字节保旧数据，或整段清空重新同步，本文实现取前者。

状态机一次处理一个字节，接口是 uint8_t data, uint8_t* frame_buf, uint32_t buf_size：帧头匹配后按长度字段收齐数据、核校验，全部通过才返回一帧。长度字段约定为用户数据字节数，不含帧头、长度与校验本身。

解析器本身平台无关、零依赖：喂进一个字节，拼进缓冲区，拼满返回一帧，仅此而已。FIFO 在哪、中断怎么接、帧缓冲区用完怎么处理，全是调用方的事，组件一概不管，换个平台原样编译。

帧解析与消费分两种组织方式：

• 同步：解析出一帧就退出，等这帧被消费完再回来继续解析。帧队列容量实际为 1，实现简单，吞吐偏低
• 异步：一进一出两个队列，字节流队列进、帧队列出，解析持续进行，消费者异步取帧，吞吐更高

两种组织方式都要防吃 CPU：异步的解析任务不能被上游数据喂着跑个不停；同步看似出一帧就退出，但垃圾数据永远拼不出一帧，退出条件永不满足，照样空转。这也是 NASA/JPL 嵌入式 C 规范（Power of Ten）的要求：所有循环必须有静态可确定的退出上界，不允许出现依赖外部数据的死循环。落到这里就是给每次调用设退出条件：限定解析的字节数或帧数，或限定单次占用时间；有 RTOS 就给解析任务分配时间片，到点让出。

帧头不匹配、长度超界、校验不符，任一步失败都丢弃已收内容、回到匹配帧头重新同步，脏字节不进完整帧。重新同步时不必从空白状态重来：已匹配帧头前缀与后续字节重叠时，回退到最长可续匹配位置即可，多字节帧头选数据区低概率组合可进一步降低误判。

某测量仪器的高速帧，一个包里装 25 个采样：1 个电压 + 24 个电流。要采满这一包，ADC 得做 25 次转换。但 ADC 规则组一次最多放 16 个，25 个转换怎么凑出来，就是采样结构设计的核心取舍。结论是双 ADC 双 DMA 并行，绕开规则组上限。

一包要 25 个转换

高速帧是 64 字节，载荷里 25 个采样：sample[0] 是电压（每帧 1 次），sample[1..24] 是电流（每帧 24 次），帧率约 400 帧/秒。

• 电压更新率：1 × 400 = 400 次/秒（慢信号，够用）
• 电流采样率：24 × 400 = 9600 次/秒（快信号，抓瞬态）

两路信号一个包传输，靠帧内位置区分，9 字节通道头再标注 24 个电流各自属于哪个档位。

ADC 规则组一次最多 16 个

常见 MCU 的 ADC 规则组（regular group）决定一次扫描按顺序转哪些通道，上限有限。这块芯片的规则组最多 16 个转换（SQ1~SQ16）。

25 个转换一次扫不完。要么拆成多个规则组，要么反复触发，要么用多个 ADC。怎么凑这 25 个，决定了采样时序和电流流的连续性。

单 ADC 得来回切规则组，会有时序和死区

如果只用同一个 ADC，要兼顾电压和电流，就得来回切换规则组：切到电压组转 1 次，切到电流组转若干次，再切回电压组。每次切换都要重配 ADC 的转换序列，重配期间 ADC 不干活，电流流里就出现死区。

更麻烦的是 25 超出 16：一个规则组塞不下全部转换，得拆成两个组（16 + 9），中间还要切换。切换的时序抖动和死区，对要抓瞬态的电流测量很不友好。

双 ADC 让每个规则组都够小

用两个 ADC 各管一路，问题就没了：每个 ADC 只管自己的信号，规则组只需要 1 个通道。电流 ADC 连续采电流（24 次/帧），电压 ADC 采电压（1 次/帧），两路并行，不用切规则组，电流流没有死区。

两个 ADC 对应两个 DMA 控制器，各自把采样搬进帧缓冲，电压写 sample[0]，电流写 sample[1..24]，合成一帧。

考虑过其他可能：反复触发单个 ADC 也能凑 25 个，但要精确控制电压和电流的穿插时序，和规则组切换一样容易出死区；外部 mux 切输入也要卡时序。双 ADC 的方案最干净：固件里能找到两个 ADC 基址和两个 DMA 控制器的引用，两路各扫各的，互不干扰。

比起单 ADC 来回切规则组，双 ADC 用两个转换器的代价，换来了电流的完整带宽和干净的时序。

推断边界

双 ADC 双 DMA 是最可能的结构，但来自反编译代码的片段推断。固件用 HAL 抽象层藏了大量细节，具体寄存器映射、两个 ADC 是否真正并行（还是共享时钟），未 100% 确认。这套结论不来自厂商文档，可能有错。

一台低功耗分析仪的上位机（Windows 闭源软件）有个隐患：串口链路只要丢 1 个字节，数据解析就永久错位。反馈给厂家后，他们的技术人员没意识到问题，认为代码本就会丢弃错误包，不至于失步。口说无凭，我设计了一个实验：在厂家自己的软件里加一个「模拟丢字节」按钮，当着他们的面按下去，让失步自己发生。缺陷是怎么查出来的、为什么会永久错位，见 错位、丢尾、永久失步：三态状态机把串口字节流拼成完整帧，本文不重复，只讲这个实验怎么设计、结果怎么样。

一、实验前要知道的三个事实

这款上位机的接收逻辑有三个特点，实验设计全建立在这上面：

• 软件每次固定读 64 字节，从不检查帧头，错位了也没有自己找回来的机制；
• 末尾不足 64 字节的零碎数据会被直接扔掉。这看似保护措施，其实防不住真正的风险：软件读之前先确认缓冲区够 64 字节，读取永远成功，数据流中间丢字节造成的错位照样发生，扔残段只会再白丢一笔数据。这个丢弃还会挪动对齐位置，直接影响实验效果（见第三节）；
• 解析出错时软件既不报警也不提示，界面只是波形卡住不动，看起来像是偶发卡死。

前两点决定了失步一旦发生就不会自己恢复，第三点决定了必须靠外部手段让失步「看得见」。

二、实验设计：一个「模拟丢 1 字节」按钮

在厂家的软件里加了三个小改动：

1. 界面上多一个按钮和一行状态文字；
2. 按钮按下后，抢在软件读取之前，从串口缓冲里提前取走 1 个字节。软件照样读满 64 字节，但读到的内容整体错开了一位，从此每一帧都是错位的，效果和真实链路丢字节完全一样；
3. 每收到一帧数据检查一次帧头，对齐正常显示绿色，错位显示红色。

按钮只是触发器，缺陷不是我们注入的，这一点必须说死。有人会问：USB 有校验和重传，丢也是整包丢，一帧正好一个包，怎么会错位？问得对，整包丢失确实不造成错位。但要分清契约和现象：虚拟串口对应用层就是字节流管道，驱动从不承诺按 64 的倍数交付，"缓冲区总是整包倍数"只是当前链路上观察到的行为，不是任何一层的保证。何况字节流脱离整帧网格有两条现实路径：设备侧，复位瞬间吐杂讯、固件发送缓冲溢出截断，丢的就不是整帧；主机侧更讽刺，这个软件收到设备报错会在接收线程里直接弹对话框，弹窗没人点，接收循环堵死，几秒后驱动缓冲溢出，溢出丢多少字节就不受控制了。也就是说它不需要任何外力，自己就能把自己逼到错位。而原厂代码没有从错位中恢复的任何能力：数据主路径从不检查帧头，认不出的帧静默丢弃，既发现不了也找不回来。公允地说：正常链路、正常固件下它确实不会出错，对齐是传输层免费提供的；但低概率不等于零，长时间挂机总会撞上扰动，而它对异常零防御、零感知。所以就算完全不碰这个软件，同样的失步也会发生，区别只是等多久。实验做的只是把"等一次随机扰动"变成"按一下按钮"。

三、第一次失败：失步竟然自己恢复了

第一版实验有个意外：丢了 1 字节后，软件有时过一会儿自己恢复了。查清楚原因：这台设备一帧正好 64 字节，经 USB 送达时缓冲区通常按 64 的倍数累积，读完没有剩余。被拿走 1 字节后，缓冲区总数永远差 1 才凑整，每次读完都会剩 63 字节零头被扔掉，而扔 63 等于读取位置多跳 63 位，正好把之前错的 1 位凑回来，对齐恢复。

修正办法：丢字节之后，让软件不再扔末尾数据，偏移就永远补不回来，失步确定持续。实验要证明的是「软件无法自愈」，就不能留下这条偶然自愈的路。

这里要主动交代：禁用末尾丢弃确实动了原程序的行为，但动的不是它「找回对齐」的能力，因为它从来没有这种能力。末尾丢弃从不检查帧头，恢复与否只看扔掉的字节数凑不凑巧，是运气不是机制。就算偶尔凑巧恢复，恢复之前数据已经错了很久，用户毫无察觉；真实使用中丢字节反复发生，靠巧合对齐等于把正确性交给运气。禁用它只是把随机性拿掉，让失步确定地摆在台面上。

四、实验结果：按下按钮之后

点击按钮：状态文字立刻变红「帧失步」，此后一直不恢复；波形卡住不动，其他操作也没有反应；而软件自己全程没有任何报错。必须断开连接再重连才恢复正常。整个改动只有 4 处，软件原有逻辑一行没动。

五、一条铁律：不能碰原程序的行为

改动有一条铁律：不能改变软件原来的解析逻辑，否则厂家可以说「这是你改坏的」。全程唯一的例外是第三节交代过的尾部丢弃守卫，它禁掉的是巧合自愈，不是任何有意的恢复机制。实践中踩过一个坑：注入时改错了程序内部的引用，导致软件启动握手直接失败，后来手工修正才解决。全程没有厂家源码，也没有他们的开发环境，用的是 Windows 自带工具加开源库完成全部改动。

六、这个实验的价值

两个关键取舍：故障要像自然发生的错误，不能像人为破坏；观测手段不能碰业务逻辑。这样演示才站得住。

丢字节是传输链路的事故，失步是软件自己的缺陷，这个实验把两件事分开了，厂家无法再用「链路问题」搪塞。反编译中还看到另一个模块里有一模一样的接收写法：凑满 64 字节盲读、不找帧头，说明这不是某个函数的疏忽，而是习惯性的设计模式。这套「加观测点 + 加故障点」的方法对任何闭源上位机都通用：把软件自己察觉不到的缺陷，变成对方无法否认的证据。

某测量仪器的高速帧设计有个小巧思：帧长刚好凑满一个 USB 包。同一台仪器的自动换档却有个没处理干净的环节。换档瞬间 MOSFET 的米勒电容会往测量点注入电荷，产生尖峰，上位机又不丢弃这些采样。

一帧刚好凑满一个 USB 包

高速采样帧是 64 字节，正好等于 USB 全速单包上限。一帧就是一个 USB 包，不用拆包、不用重组。

载荷 60 字节安排得严丝合缝：9 字节通道头 + 25 个采样（各 2 字节）+ 1 字节标志 = 60，一字节不剩。更巧的是 9 字节通道头 = 24 个电流采样 × 3 位通道号 = 72 位，位打包后恰好 9 字节。每个采样点独立标注所属档位。

三个约束互相咬合：USB 包大小、采样数量、通道头位宽，选出的数字恰好都凑满。这是值得抄的设计。

换档瞬间的电荷注入

自动量程靠 MOS 开关切换分流电阻和增益。换档是硬件动作：一个 MOS 管导通、另一个关断，测量回路瞬间换挡。

MOS 管栅极和漏极之间有寄生电容，也就是米勒电容。切换瞬间，栅极驱动电压快速跳变，通过米勒电容把电荷灌进漏极，也就是测量节点。对 µA、nA 级测量，这一点电荷就是很大的相对误差。开关本身的导通关断过渡还会让测量节点抖几个采样周期。

换档瞬间产生的是物理必然的尖峰，不是测量噪声。

实测抓帧能看到换档瞬间的完整过程：过渡帧里一部分采样还标旧档、一部分已经标新档（通道号混档）；换档后固件把电流采样置 0，持续几个采样周期，作为稳定期标记。稳定期结束，采样恢复正常。固件用零填充标记数据无效，没有停止采样，也没有重新编程 ADC。

上位机只读档位，不处理过渡

上位机逐采样读通道号，按通道号套对应的校准系数，把当前档位显示出来。通道号一变，显示跟着变。

固件给了零填充作为稳定期标记，上位机却不认。过渡帧、零采样都被当成正常数据照常处理。帧里唯一的标志字节只用于电压校准模式选择，跟换档无关。上位机既不知道换档发生的时间，也不在乎过渡采样脏不脏。

尖峰混进数据的后果

低功耗测量里，换档尖峰可能被当成真实的电流瞬态。设备唤醒脉冲本来就该是尖峰，真假混在一起，结论就错了。

平均和滤波救不了尖峰：尖峰是有偏的，会把均值抬高，让功耗估算偏大。触发和告警可能被尖峰误触发，出现假告警。

换档越频繁，污染越多。读数在量程边界附近跳动时最容易换档，那也正是数据最需要准确的时候。

处理办法

换档瞬态是物理必然，靠软件消化：

• 固件侧：换档后置零标记稳定期（实测该仪器如此），上位机识别零点后丢弃。
• 上位机侧：看到通道号变化，跳过过渡帧或过渡采样。
• 显示侧：对尖峰做合理性校验，明显偏离相邻采样就剔除。

帧设计能凑满一包 USB 是巧思，换档瞬态同样值得花心思。测量仪器最怕的，是假数据。

推断边界

以上换档行为来自实测抓帧，可信度较高。电压与电流各自独立采样的双 ADC 结构来自反编译代码的片段推断，具体寄存器映射和通道号未 100% 确认（固件用 HAL 抽象层藏了大量细节）。整套机制是逆向分析结果，不来自厂商文档，可能有错。

自动量程就是迟滞触发：读数太高升档，太低降档。升档和降档如果画在同一条线上，读数在阈值附近晃一下，两个档位就会来回横跳。显示难看，噪声被放大，换档瞬态还可能把电路推自激。

办法也只有这一条：升档线和降档线分开，中间留下死区。

• 升档线靠近满量程，比如 95%。当前档快饱和了再换。
• 降档线靠近见底，比如 10%。当前档灵敏度过剩了再换。
• 死区必须大于噪声带。噪声是 ±2%，死区就得远大于 4%，否则一次尖峰照样来回踩线。

量程如果是十倍程，滞回还会再被拉开一截。旧档 95% 升上去，同一物理量在新档只剩 9.5%；要降回来，还得跌到新档 10% 以下，相当于旧档的 1%。物理量要变两个数量级才会反向换档。

换档后再空几个采样不评估，挡住电路建立期的毛刺就够了。参数不用精调，先让死区盖住噪声，横跳自己会停。

项目背景

低功耗调试离不开 µA 级电流测量。英加 EMK850+ 只有 Windows 上位机，没有对外接口，功耗数据进不了脚本，批量测试、回归测量、AI 辅助优化全部做不通。

本项目独立逆向其串口协议，用 Python 实现命令行工具与 MCP/REST 服务器，把测量与供电控制变成 HTTP 接口，脚本、CI、AI 客户端可直接调度，形成采集、控制、优化闭环。

「闭源仪器协议逆向 + MCP 服务化」这套做法，可复用到任何只有上位机的台式仪器。

核心工作

1. 串口协议逆向：原厂上位机是 .NET 程序，用 ILSpy 反编译直接拿到完整通信协议，帧结构、命令表、换算公式整理成协议文档。
2. AI 辅助实现：定义协议规范与验收标准，驱动、CLI 与服务器代码借助 AI 工具生成，帧行为逐项与真机实测比对校验。
3. 流式帧同步：USB CDC 流式传输不保证按包交付，解析采用逐字节流式帧同步状态机，拆包、粘包、错位下稳定出帧。
4. MCP/REST 服务化：单进程同时提供 REST 与 MCP（Streamable HTTP）接口，覆盖测量、采样、供电控制，Claude、Cursor 通过工具发现自动接入。
5. 断电复位唤醒：可编程电源断电重启，唤醒深度休眠后调试器断连的 MCU。

设备效果

python emk850_analyzer.py power COM19

电压: 4.202 V   电流: 6.940 uA   功耗: 29.20 uW

项目边界

• 协议为独立分析归纳，与厂商无关，固件升级可能失配
• 断电通过设 0mV 间接实现，实测测量端仍有约 2.6V，是否真正断电需万用表确认
• 串口独占，不能与原厂上位机同时使用；空载清零需断开所有负载

GitHub 仓库：Yingjia_EMK850_low-power_analyzer_MCP · 协议文档 EMK850_PROTOCOL.md

嵌入式行业中，厂商常通过加密保护固件知识产权与设备运行安全，但大量方案从架构设计阶段就陷入同一个误区：把解密密钥与核心逻辑部署在用户完全可控的上位机环境里。

近期分析某测量仪器的固件升级链路时，验证了这一设计的必然失效：服务器下发的固件包全程加密，表面防护逻辑完备，实则解密密钥、盐值、算法参数全部硬编码在 PC 端上位机程序内。抓取加密固件包后，直接复用程序内置的解密流程，即可完整导出明文下位机固件。全程未涉及算法破解与暴力攻击，只是复现了厂商烧录流程的前置步骤。

失效根源：信任边界错位

这套方案从架构上注定无法实现真正的固件保护，问题集中在三点：

1. 方案采用对称加密，加解密共用同一个密钥。烧录动作由上位机触发执行，密钥必须内置到客户端程序里。
2. 上位机运行在用户完全掌控的通用计算环境中，无论密钥以硬编码、资源隐藏还是动态派生方式存储，都能靠反编译、内存抓取、字符串检索等常规手段提取。
3. 固件头部的初始化向量、盐值都以明文存储，完整性只靠哈希校验，没有数字签名机制。既挡不住固件提取，也防不了恶意篡改。

此类设计中的"加密"，本质只是一层文件级混淆，只能拦住无意翻看临时目录的普通用户，对有明确目标的逆向分析者不构成有效防护。

正确防护：把信任根锚定在设备端

真正可靠的固件保护，核心原则只有一条：密钥与解密逻辑始终不脱离受保护的硬件环境。上位机只做数据传输通道，不参与任何解密与校验。在此基础上，按下位机硬件能力选型加密方案。

硬件支持加密模块：优先硬件级加解密

若下位机芯片内置 AES、DES 等硬件加密外设，或带 HSM/SE 安全模块，优先用硬件加速方案：

• 服务端用对称算法完成固件加密，密钥只存在于厂商内部可信环境，绝不下发上位机。
• 解密由芯片硬件模块完成，密钥存在芯片专用安全区域或一次性可编程区域，外部无法读取。
• 硬件级加密既保障加解密性能，也提高密钥泄露的门槛。

硬件无专用模块：用轻量软件加密

若下位机资源有限、无硬件加密能力，可选 ChaCha20 这类轻量高效的软件加密：

• 服务端用 ChaCha20 加密固件，密钥同样只保存在服务端。
• 设备端用软件实现解密，密钥固化在芯片 Flash 内部，开启读保护与代码访问限制，阻止外部读取。
• 该方案不需要额外硬件支持，资源占用低，能在绝大多数通用 MCU 上落地。

进阶安全加固

在解密逻辑下移的基础上，按硬件条件叠加防护：

• 固件增加数字签名校验，设备端烧录前先验签再解密，防恶意固件注入。
• 开启芯片安全启动链，逐级校验固件完整性，构建从 Bootloader 到应用层的信任链。
• 启用芯片读保护、代码保护，防止通过调试接口直接读取固件。

结语

固件加密的安全上限，从来不由加密算法的复杂度决定，由密钥的存放边界决定。

把解密密钥交到用户可控的上位机手里，再复杂的算法也只是形同虚设。把信任根牢牢锚定在设备端，哪怕是轻量加密方案，也能构建有效的防护屏障。

EMK850+ 是一台低功耗分析仪：经 USB 虚拟串口（115200）连电脑，持续回传电流/电压采样流，nA 到 mA 自动换挡。低功耗测试的常态是让被测设备长时间挂机，看完整的功耗曲线，采样数据只能经配套上位机读取。

但这个上位机撑不住挂机：连续运行接近 1 小时就卡死。我反编译了它的接收代码定位缺陷，再重写了一个流式解析器替换。

• 问题：上位机按 64 字节整块读取，流中间丢一个字节，之后每帧永久错位；另一处阻塞读没有超时，USB 断流时线程挂死。
• 我的工作：反编译厂商上位机（.NET 4.7.2，ilspycmd）取证；搭两级线缆衰减链路复现故障；用 Python 重写解析器，三态状态机逐字节同步。
• 结果：校验失败每次只丢一个字节，自动回到帧头扫描；实测约 400 帧/秒持续采样，无失步、无挂死。

串口字节流没有帧边界

串口物理层按字节连续传输，协议层把若干字节聚成帧。帧边界只能由帧头特征和长度字段给出：本协议帧头是 0x33，第 3 字节 len 声明载荷长度。接收端拿到的是不断流出的字节序列，线上没有"这条消息结束"的信号。

按固定长度切块因此是一种强假设：缓冲区起点恰好是帧起点。这个假设不由协议保证。接收端读得快、事件在帧边界触发，假设成立；读慢一拍、事件在帧中间触发，假设失效。

反编译取证：上位机接收的两类缺陷

反编译 EMK850+ 上位机（.NET 4.7.2，ilspycmd），主接收函数 MainWindow.SysReceiveData 按 64 字节整块读取：

while (serialPort.BytesToRead >= 64) {
    serialPort.Read(array, 0, 64);
    Protocol prot = (Protocol)Utils.BytesToStruct(array, typeof(Protocol));
    HandleProtocol(prot, array);
}
if (serialPort.BytesToRead > 0 && serialPort.BytesToRead < 64) {
    serialPort.Read(array, 0, serialPort.BytesToRead);   // 尾包直接丢弃
}

主路径上每次 Read(array, 0, 64) 都能凑满 64 字节，读取本身从不失败。真正的脆弱点是：这 64 字节未必等于完整一帧。字节流中间一旦出错，读到的 64 字节就变成跨帧的错位窗口，内容全是错的。

接收逻辑的缺陷分两类。第一类是错位：整块读取有三个具体缺陷点。

1. 无帧头扫描、无重新同步。主接收路径拿到 64 字节直接按 cmd 分发，不校验 0x33；采样数据分支（cmd 33/132）同样不看帧头。个别配置响应分支里虽有 buffer[0]==51 的判断，失败仅静默丢帧，不构成重新同步。对齐一错，后面每帧都错。
2. 尾包无条件丢弃。每个接收事件结束时缓冲被清空，不足 64 字节的残段直接丢掉（源码日志原文就是"抛掉 N 字节数据"），既丢数据又加重失步。
3. 结构体盲解。Utils.BytesToStruct 直接 Marshal.Copy 64 字节；错位后 cmd 是垃圾，按它分发即静默误判。

第二类是挂死：无超时的阻塞读。calWindow 直接 Read(array, 0, 64) 不检查 BytesToRead，且全代码未设 ReadTimeout（.NET 默认无限超时）。USB 流中断、凑不满 64 字节时，该事件线程永久挂起。错位导致数据损坏，阻塞导致挂死，两类缺陷独立。

一次错位引发的永久失步

每次 Read(array, 0, 64) 都能凑满 64 字节。而且正常情况下对齐是白捡的：设备一帧正好 64 字节，经 USB 送达时一帧一个包；USB 自带校验和重传，坏包不会交付半个，丢也是整包丢，而整包丢失不破坏对齐，只是数据少一帧。但这只是观察到的行为，不是契约：虚拟串口对应用层就是一根字节流管道，操作系统和驱动从不承诺按包交付，经过驱动缓冲、集线器、隔离器之后，BytesToRead 出现任何字节数都合法，换个电脑、换个驱动版本行为就可能变。把解析正确性押在传输层的实现细节上，本身就是隐患。真正会坏的是字节流脱离 64 网格的情况：设备复位瞬态往流里吐杂讯、固件发送被截断，字节数不再是 64 的整数倍，流的对齐从此永久偏移。

读窗口固定是 64 字节，帧变短也不会让窗口调整位置。字节丢在某个帧的中间时，这一帧变短，它后面的所有帧整体前移。上位机仍按原来的 64 字节位置读，于是每个读窗口都跨在两帧之间：0x33 落在错误位置，cmd 读错，整帧报废。块读没有任何手段把偏移找回来，错位持续到重连。

错位一旦发生，代码里没有任何路径把同步找回来：不扫描帧头，不清空缓冲从下一字节继续。

实测复现：我搭的测试链路是 电脑 → USB 延长线 → USB 隔离线 → 分析仪，两级线缆叠加让 USB 信号衰减、链路更容易出错。设备经该链路连续挂机，官方上位机接近 1 小时卡死。该设备是 STM32 USB CDC 虚拟串口，对连续流没有硬件流控，链路劣化让设备反复复位：复位杂讯让字节流脱离 64 网格造成错位，断流撞上无超时的阻塞读造成挂起，错位无法自愈，挂起不可恢复，最终都表现为卡死。

要公允地说一句：正常链路、正常固件下，这套块读不会出错，它的对齐是传输层免费提供的。缺陷不在"会出错"，在"出错时零防御、零感知"：概率低，但现场挂机总会撞上，撞上就是永久失步，软件自己还毫无察觉。

三态状态机：等帧头、收头部、收载荷

流式解析的核心：任何时刻只维护少量状态，逐字节推进，校验失败只丢弃当前这一个字节，然后继续。

三个状态（括号里是代码里的状态名）：

• 等帧头（WAIT_MAGIC）：逐字节扫描，遇到 0x33 进入收头部。其他字节直接丢弃。
• 收头部（HEADER）：收 cmd / len / seq 三字节，校验 len <= 60。通过进入收载荷；失败丢弃当前这一字节，回等帧头继续。
• 收载荷（PAYLOAD）：收满整帧 64 字节（len 之外自动补零），出帧并回等帧头。帧级不设累加和校验，校验只做在收头部的 len <= 60。

三条纪律：

1. 每次只丢一个字节，绝不整帧丢弃。
2. 校验失败不清空缓冲，从下一字节继续扫描。
3. 收完整帧回到等帧头，处理流中下一帧。

状态机解决错位，超时解决挂起。串口读必须带超时：项目实现用 serial.Serial(port, 115200, timeout=0.2)，读不到就超时返回，USB 断流时只是没有数据，不会永久阻塞。

项目实现见 tools/emk850_proto.py 两段式解析：FrameDecoder 逐字节状态机出 64 字节帧，ProtocolParser 按 cmd 分发。实测高速数据流约 400 帧/秒持续采样，无失步。

流式解析的适用边界

整块读取在某些条件够用：设备固定节奏发满定长帧、接收端跟得上、错位后重连成本可接受。这类场景块读代码简单，是务实选择。

需要流式解析的场景：复位瞬态吐出杂讯、半帧、多帧交错，或数据速率高、接收端可能瞬时滞后。这类场景任何一次错位都会让块读永久失步。

本协议判断完整帧的要素是帧头字节 + 长度字段；累加和只用于配置大块数据的重组，帧级不校验。换其他协议，把等帧头状态的匹配字节换成对应帧头即可，三态结构不变。

背景

电池供电的直流电机执行器经霍尔脉冲反馈位置/转速，并借零点霍尔信号回零；控制器以"位置外环 + 速度 PI 内环 + 速度前馈"完成定行程运动。鉴于续航与噪声约束，PWM 载波频率需权衡开关损耗、绕组纹波及噪声，因此对载波频率做了系统性扫频寻优。

工作内容与成果

• 搭建 AI 驱动的自动化测试环境：逆向低功耗分析仪的通信协议，将其封装为 MCP（Model Context Protocol）工具，打通固件烧录与串口指令下发链路，使 AI 能够自主完成固件烧录、运动控制指令发送和能耗数据采集。人工仅负责初始环境搭建与早期联调监督，之后由 AI 无人值守自动完成全频带扫频测试。
• 固定行程测量能耗：由低功耗分析仪同步采集固定行程内的输入电压与输入电流，对瞬时输入功率积分得到行程输入能耗；每频点重复 10 次，被测机全程常唤醒以消除低功耗睡眠唤醒干扰。
• 扫频寻求最优参数：实测固定行程输入能耗随载波频率呈 U 型曲线，定位本机最低能耗点，其测量中心值较原设定频点降低约 11.5%；高频端能耗明显抬升，与频率相关损耗增加的趋势一致。

实测扫频结果

损耗机理

在电流连续、平均电流近似不变，且 PWM 周期远小于电机电气时间常数 τe = L/R 的近似下，电流纹波满足 ΔI ∝ 1/f，由纹波引入的额外绕组铜损可写成 P_ripple ≈ k₂/f²。当单次开关能量近似不变时，驱动器开关损耗可写成 P_sw ≈ k₁f。加上与载波频率近似无关的基线损耗 P₀，总损耗可近似表示为 P_total ≈ P₀ + k₁f + k₂/f²；该模型用于解释 U 型趋势，不代表本次扫频完成了各项损耗的独立测量。本文以扫频实测结果为准，不将损耗分解为独立项进行数学拟合。

一块 ESP32-C3 电源控制板，Web 前端通过 HTTP API 控制电源，WebSocket 推实时采样曲线。打开输出后刷新页面，输出按钮显示「已关闭」，实际输出保持开启。后端接口返回的状态正确，问题出在页面加载时前端同时发出多个 HTTP 请求：C3 的 httpd 只处理第一个，其余连接全部被重置。本文记录复现过程、原因和前端串行化修复。

现象：刷新后输出按钮显示关闭，输出实际开启

打开输出后刷新网页。输出按钮显示「已关闭」，电源输出实际保持开启。按钮状态没有同步到真实状态。

复现：并发 HTTP 请求第二个必被 ECONNRESET

先排除后端。用 curl 直查 /api/getSystemStatus，返回 is_output_on: 1，与实际状态一致。后端是实时查询 PSU，返回值正确。

再看前端。页面加载时同时执行三个接口请求（get_memory_preset、getSystemStatus、get_output_status），并建立 WebSocket 连接。用 node 脚本模拟这个行为：

• 同时发两个请求，第一个 200，第二个报 read ECONNRESET；连测两次结果一致。
• 同时发三个快速接口（get_config、debug.json、network.json），也只成功第一个。
• 把请求改成串行，三个全部成功（getSystemStatus 1559ms、get_output_status 1904ms、get_memory_preset 920ms）。

结论：这台 C3 的 httpd 同时只处理一个请求，并发到达的其余连接被重置。

原因：单任务 httpd 加 PSU 慢查询占住处理循环

esp_http_server 是单任务模型。httpd 配置 max_open_sockets=7（C3 上限），lru_purge_enable=true。处理一个请求期间，并发到达的连接得不到处理，被 httpd 关闭，客户端收到 ECONNRESET。快速接口并发也失败，重置来自 httpd 单任务处理能力本身，与处理器快慢无关。

PSU 串口查询把问题放大。AST2/AST4/AST5 每条查询要约 1.5s（仪器把应答拆成多个小块、间隔约 300ms 吐出）。慢查询占住 httpd 任务时，并发到达的连接更明显被重置。

前端 .catch 把失败吞掉，界面停在初始值。getSystemStatus 失败后 isOutput 保持初始 false，按钮显示「已关闭」。

修复：前端请求队列串行化

让所有 HTTP 请求进同一个队列，前一个完成（成功或失败）再发下一个，任何时刻只有一个请求在飞。

var apiQueue=Promise.resolve();
function api(path, opts){
  var run=function(){
    return Promise.race([
      fetch(path, Object.assign({headers:{'Content-Type':'application/json'}}, opts||{}))
        .then(function(r){return r.json()}),
      new Promise(function(_,rej){setTimeout(function(){rej(new Error('timeout'))},10000)})
    ]).catch(function(e){showMsg('请求失败: '+path,'err'); throw e});
  };
  var p=apiQueue.then(run, run);
  apiQueue=p.catch(function(){});
  return p;
}

要点：

1. apiQueue 保存前一条请求的完成状态，新的 api() 用 apiQueue.then(run, run) 排队，队列空闲后才执行。
2. apiQueue=p.catch(...) 吞掉错误，队列链不断，失败的请求不会卡住后续请求。
3. 10s 超时兜底：PSU 查询挂死时队列不会被永久卡住。

WebSocket 握手也是 HTTP 连接。页面加载时先走完状态请求，队列清空后再 connectWS()，避免握手和 API 抢连接被重置：

syncStatus();
loadPreset();
apiQueue.then(connectWS);

加载顺序上先查 getSystemStatus，输出按钮在首个请求完成（约 1.6s）后即反映真实状态。串行加载三个查询全部成功，状态同步恢复。

边界：嵌入式前端的并发策略

串行化修复了这台 C3 的并发重置。前端不能假设设备有浏览器一样的并行请求能力，嵌入式 httpd 场景按这几条控制：

1. 前端请求串行发送，任何时刻只允许一个请求在飞。慢查询占住 httpd 时并发请求全被重置。
2. 合并接口、减少往返。多个状态能一次查询就一次返回，减少慢查询次数。
3. 慢读取在后端做缓存或批量，让 httpd 处理器尽快返回，缩短占住单任务的时间。
4. 实时数据走 WebSocket 批量推送（配合降采样），避免高频 HTTP 轮询挤占连接池。

任务背景：为电源控制板搭建 INA228 采样管线，在 ESP32-C3（160MHz）上用位总线 I2C 连续采样电压电流。目标是把采样率从 1kHz 提升到 2kHz。本文说明采样管线为何采用「中断只发事件、高优先级任务做读取」的架构，以及 2kHz 受三条约束限制、最终稳定在 1kHz 的边界。

采样管线：中断→事件→高优先级任务→软件 I2C

esp_timer 以 1kHz 触发采样，回调里只做一件事：xTaskNotifyGive 向读取任务发事件。真正的位总线 I2C 读取、ADC 换挡、样本入队，全部在一个高优先级实时采样任务里完成：

static void sampling_timer_cb(void *arg) {           /* esp_timer 任务上下文 */
    xTaskNotifyGive(s_reader_task_handle);            /* 只发事件，不做 I2C */
}

static void ina228_reader_task(void *parameter) {     /* 读取任务 */
    while (1) {
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        ina228_sample_t s;
        ina228_read_sample_fast(&s);                  /* 慢的位总线读取 */
        xQueueSendToBack(par20_sensor_queue, &s, 0u); /* 样本入队 */
    }
}

为什么不直接让 esp_timer 回调读 I2C？这个候选方案在 2kHz 下被看门狗否决：回调每次要跑 ~1ms，esp_timer 任务连续被长回调占住，IDLE 任务饿死，任务看门狗复位设备。esp_timer 任务还托管显示、WiFi 等其它定时器，把 I2C 读取塞进去等于用最忙的一条线程干最慢的活。

读取任务取高优先级保证采样实时性：事件通知一到就立即执行位总线读取，不被其它业务线程拖慢。下游一个 LTTB 降采样消费者每 200ms 取 10 个代表点（50 点/秒），只推电压和电流，经 WebSocket 给前端图表。

软件 I2C 而非硬件 I2C：400kHz 上限

不用 C3 的硬件 I2C 控制器，原因是硬件 I2C 上限 400kHz；此外这块板上原生 I2C 控制器曾经把状态机卡死在临界区（代码注释有记录），所以沿用原固件的位总线方案。

位总线理论上可以更快：原 SoftWire 声称 3MHz。实际能跑多快，取决于 GPIO 操作的开销，而不是协议本身。

GPIO 寄存器直写：读取从 1ms 降到 240µs

驱动函数 gpio_set_level() / gpio_get_level() 带校验开销，实测把位总线压到 ~100-200kHz，一次 6 寄存器全读要 ~1ms。

改成直接写 GPIO 寄存器：out_w1ts/out_w1tc 置位/清位，in 读输入。同样的位翻转逻辑，单次读取降到 ~240µs。

实测 SCL 频率：按 I2C 协议位数换算，快速读取（216 个 SCL 时钟）240µs ≈ 0.9MHz，全量读取（360 时钟）340µs ≈ 1.06MHz。位总线实际跑在 Fast Mode Plus（1MHz）档位，超过硬件 I2C 的 400kHz 上限约 2.5 倍。

顺带两个小优化：ADC 范围缓存（不每次读 CONFIG 寄存器），energy/charge 每 10 次采样才读一次（LCD 和 WebSocket 都不用这两个字段）。

2kHz 的三重约束与 1kHz 的 CPU 边界

要上 2kHz，位总线读取必须同时满足三条约束：

1. 读取不能占用托管周期回调的任务：esp_timer 任务承载显示、网络等所有周期回调。若把 ~1ms 的位总线读取放进回调，2kHz（500µs 周期）下回调占满 esp_timer 任务，其它定时器被饿死，IDLE 无法喂看门狗 → 设备复位。慢读取必须移出 esp_timer 任务。
2. 读取耗时必须小于采样周期：读取交回独立任务后，未优化的位总线一次全读 ~1ms，仍大于 500µs 周期。任务连续运转、无法让出 CPU → 看门狗。读取必须压到周期以内。
3. 读取 CPU 占用不能挤占网络业务：位总线优化后读取 ~240µs，2kHz 下读取任务占 ~50% CPU。持久 WebSocket 连接下网页加载被拖到 2.7 秒。

1kHz（周期放宽到 1000µs，读取占 ~24% CPU）同时满足三条，网页恢复正常（~0.4 秒）。这是 C3（160MHz，已是上限）+ 位总线 I2C 的实用边界。要真正上 2kHz，只能换硬件 I2C 控制器，把读取从任务里挪进硬件。

架构边界与移植结论

采样管线的正确形态：中断只发事件，慢的位总线读取交回一个高优先级任务。位总线提速靠 GPIO 寄存器直写，而不是带校验的驱动函数。2kHz 对这台 C3 不成立，1kHz 是 CPU 占用允许的极限；要更高采样率，需要换掉位总线方案本身。

声明： Modos-Labs 的 Glider 与 Caster 是开源项目，作者为 Wenting Zhang（GitHub: Modos-Labs）。本文是阅读该项目源码和文档后整理的学习笔记，用于理解墨水屏高刷的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中所有工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

项目仓库：github.com/Modos-Labs（Glider 开源墨水屏显示器 / Caster Verilog EPD 控制器）

微胶囊电泳与双稳保持

墨水屏每个像素由无数微胶囊组成，胶囊内悬浮着带相反电荷的黑白颜料颗粒，浸泡在透明油中。给像素施加正电压，一种颜色的颗粒被吸向观察面、另一种沉底；反压则相反。寻址使用 2D TFT 阵列加电场，行列扫描方式与 TN/IPS 液晶同源。

与液晶的本质差别在保持机制：液晶易失，撤掉电场后分子松弛回原点，必须每帧持续刷新并耗电；墨水屏双稳，驱动完成撤场后图像自行保持，零场零功耗。Kindle 关机仍显封面即源于此。

控制器按波形表逐帧驱动

真实驱动并非恒定直流电压。为得到干净灰度，控制器从波形表（waveform LUT）读出一串时序脉冲，逐帧发给每个像素，每像素跑自己的状态机直到抵达目标灰阶。

颗粒在油中电泳迁移需要时间，单次黑白翻转约 9 个驱动帧、物理上约 150ms。这一段是流体迁移下限，控制器无法突破。控制器还要做 DC 平衡、整屏闪刷清残影、防过驱欠驱。因此刷新是控制器主动逐帧编排的过程，并非面板自主完成。

全局计数器造成的帧率排队

普通 EPD 控制器（EPDC）用一条全局计数器查波形表，整屏共用一条时间线。上一次整屏刷新未走完，新画面不受理。一次刷新约 100ms，把图像可受理速率钉在约 10Hz。这 100ms 里颗粒早已停下，延迟纯属架构排队。

用户感知的卡顿多来自这层排队，并非 150ms 物理迁移。

每像素局部计数器与早取消

Caster 删掉全局计数器，给每个像素在自己的显存里塞一个 6-bit 局部计数器，各自独立记帧序、各自查波形。

早取消（early cancellation）：像素驱动到一半目标变了，不必先走完全程再掉头。控制器按已走比例重算返程帧数（csr_b2wframe - pixel_framecnt + 1），省下的正是排队时间。

混合灰阶：变化时用 fast-binary 以 85Hz 跟手，静止约 1 秒（AUTOLUT_QUIET_FRAMES=60）后自动用 LUT 重绘 16 级干净灰阶。

FPGA 在此处的本职是并行与确定性低延迟：每像素独立状态机为纯组合逻辑，4 像素/时钟，抖动为零；视频流直通处理低于 20µs，因此走 DVI/DP，不走 USB/SPI。每像素每帧读改写 16bit 状态，1080p 约需 540MB/s 带宽，板上因此挂 DDR3-800。

硬件并不夸张：仅用 Spartan-6 LX16 的 1704 个触发器。物理 150ms 没有突破，高刷消掉的是卡顿感：输入零排队、每像素随时掉头、停下才精绘。看书场景下这套优化无收益，当显示器才需要。

打开交互 Demo

单色屏开发卡在 AI 看不见屏幕

OLED、单色点阵屏（12864 那类灰白屏）、墨水屏这类单色屏资源有限，跑不动 LVGL 一类重型 GUI。单色屏图形库的事实标准是 U8G2：支持几十种屏幕控制器、字体库庞大、内存占用极小。

但 U8G2 开发很慢：改一次显示效果，要重新编译、烧录、上板看，一轮几十秒到几分钟。AI 写的 U8G2 代码经常能编译过、屏幕不对，字体、坐标、布局来回调都对不上。AI 看不见屏幕，写完只能等人烧录反馈，迭代闭环断在它看不见的地方。

为了让 AI 能独立把单色屏界面做对，我把它需要的环境直接搬进浏览器：一份像素级还原 U8G2 的纯 JS 仿真，AI 在这里生成代码、实时预览、截图自检，确认效果对了，再把同一份代码挪到嵌入式真机。

浏览器里的像素级仿真闭环

把 U8G2 完整移植成纯 JS 后，AI 在浏览器里就能跑通整个闭环：

1. 开发 U8G2 显示界面（JavaScript，浏览器原样运行）
2. 视觉验证：AI 自己运行、截图、识图，把 UI 闭环
3. 自动化测试：AI 在浏览器上跑测试，提前排除错误隐患
4. 用户确认：效果符合预期即通过
5. 部署：同一份代码上真机（与原生 U8G2 C 库 API 一致）

显示逻辑在浏览器里提前验证，问题不用等到上板才发现。

U8G2JS 项目： github.com/createskyblue/u8g2-js

Demo 仓库： createskyblue.github.io/u8g2-js/

用仿真环境做出的墨水屏传感器趋势界面

仿真环境最大的价值，是能低成本反复试错。下面这套单色墨水屏传感器趋势界面，就是 AI 在浏览器里迭代出来的：

• CO₂ 曲线趋势：渐变填充分两步，先在独立灰度通道按曲线生成深浅渐变，再用误差扩散把灰度量化成黑白点阵叠加到屏幕，整体墨量近似守恒，观感平滑，全程整数运算，符合嵌入式无浮点约束
• PM2.5 三粒径趋势：多曲线同屏，靠抖动区分层次
• 温湿度双曲线：双轴对照，信息密度压进单色屏

仿真器逐字节一致的实现

浏览器里的效果必须和真机一模一样，否则仿真毫无意义。这部分是仿真器的核心。

逐行移植 C 渲染引擎

移植没有走 WASM 或自动转译，直接对照 C 源码逐行手写 JS：同一套算法、同一种控制流，连字体格式和帧缓冲的字节布局都保持一致。浏览器端能直接读源码、改算法，AI 也容易理解和修改。

与原版 C 库逐字节对拍

手工移植最怕大概一致。做法是把原版 U8G2 C 库用 gcc 编译出来，跑 18 个场景（文本、图形、旋转、裁剪、XOR、按钮、Unicode、全量中文），每一帧都与 JS 输出逐字节比对，0 字节差异。验证脚本可复现，改完核心代码重跑一遍即可确认没有偏差。

像素级还原细节

• 帧缓冲、字体 RLE 位流、draw_color 0/1/2、旋转，输出与真机逐字节一致
• 字体运行时加载：字体就是字节数组，运行时代码里直接 load / fromBase64 载入任意 U8G2 字体
• 内置全量中文字库：宋体 12/16/24px，约 2.8 万字形，AI 写的中文直接渲染
• 零依赖开箱即用：纯 ESM，浏览器 file:// 双击 demo 即可运行，Node 可无头测试
• API 与真机一致：Arduino U8g2lib 风格 camelCase 加 C 风格别名，仿真代码可直接平移到硬件

快速开始

import { U8g2, U8g2Font } from './src/index.js';
const u8g2 = new U8g2({ display: 'ssd1306_128x64_noname_f' });
u8g2.setFont(U8g2Font.fromBase64('AP//AA...'));
u8g2.drawStr(0, 10, 'Hello');
u8g2.sendBuffer();
u8g2.attachCanvas(document.getElementById('screen'));

本地运行

python -m http.server 8765 --bind 127.0.0.1

然后访问 http://127.0.0.1:8765/。

声明： Turning Impedance into Frequency: An LC Experiment 是一个开源项目，作者为 nobcha（Hackaday 项目页）。本文是阅读该项目源码与文档后整理的学习笔记，用于理解「阻抗转频率」式 LC 测量的工程实现方式。本文作者不是该项目的开发者，未参与该项目的任何代码贡献。 文中工程细节均来自对开源代码的分析，不代表本文作者的设计决策。

性能很弱的 MCU 也能完成 L/C 测量。这个项目给出的做法是：根本不用 MCU 去做采样或信号生成。待测电感或电容被放进 LC 谐振槽，由 74HCU04 反相器构成 Franklin 振荡器，输出频率由 f = 1/(2π√(LC)) 决定。MCU 只负责数这个频率。阻抗到频率的映射全部发生在模拟物理层面，代码里没有任何 ADC 或相位解调。

谐振频率映射阻抗的物理机制

传统阻抗测量（例如 VNA）需要注入扫频信号、同步采样电压与电流、再解算复阻抗。这个项目的做法绕开了整条链路：把待测件接入谐振槽，让振荡器自发工作在由槽路参数决定的频率上。

关键点在分工：74HCU04 加 LC 槽是真正的模拟前端，承担阻抗到频率的全部转换；ATmega328P 不参与波形生成，也不做任何模拟采集。复杂度下沉到电路，MCU 退化为一个计数器。

MCU 闸门计数与共振方程

ATmega328P 通过 FreqCount 库，在 1 秒闸门内对 Pin 5 的上升沿计数，直接得到整数频率。固件做两件事：

• 校准：DPDT 开关把 1000 pF 参考电容切入槽路，测两次频率 F1（无 Cref）与 F2（有 Cref），由 C0 = Cref / (ratio² − 1) 和 L0 = 1 / ((2π·F1)² · C0) 解出槽路等效参数。
• 测量：把待测件接入槽路后测频率 f，由 L = 1 / ((2π·f)² · C0) − L0 反推未知量。

全文检索不到 analogRead、analogWrite、tone 或任何 ADC、同步采样调用。MCU 的全部负担是数脉冲加几行浮点除法。

复阻抗塌缩为标量频率的测量边界

振荡器只输出一个频率 f，它只反映槽路的净电抗。这一简化带来四个硬性边界：

• 一次只能解一个未知量（L 或 C），且必须已知槽路拓扑。
• 测不到电阻、ESR、Q 值、D 因子与相位，标量频率无法分离实部与虚部。
• 待测件必须物理接入谐振槽，属于侵入式测量，不能在板在线测量。
• 单频单点，无法刻画组件随频率变化的特性。

适用边界与设计取舍

优势是硬件极简、电路透明，下限可到约 0.1 μH 小电感，成本远低于 VNA。

取舍同样明确：作者以结构清晰为目标，不追求绝对精度；每次上电或温度显著变化需重新校准，量程被固定 1–2 MHz 的槽路锁死，且 f 对 L 的映射是非线性的。

选型建议：只关心单个 L/C 的数值、且希望用最廉价 MCU 完成时，这套方案合适。需要复阻抗矢量、Q 值或在板测量时，仍应使用 VNA。

Patent Disclosure Skill 是一个辅助编写专利技术交底书的开源 Skill，适合需要把已有技术材料整理成正式交底书的人。

实际使用结果

这次我花了 20 块钱，烧出了一份非常高质量的专利交底书。最终成品的完整度和表达质量都超出了我的预期，我非常满意。

整个使用体验很直接，最后得到的结果也很扎实。只说结论：这玩意非常好用，我很推荐。

开源项目地址

GitHub：https://github.com/handsomestWei/patent-disclosure-skill

免安装、浏览器即用的极简通信调试平台。串口、蓝牙、WebSocket 三合一，实时收发 + 关键词染色 + 数据提取。

• GitHub：https://github.com/createskyblue/web-serial-monitor
• 在线使用：https://createskyblue.github.io/web-serial-monitor

快捷发送	染色和提取

🚀 王炸特性

三种通信模式

• 串口 — Web Serial API，免驱动，Chrome/Edge 直接开用
• WebSocket — 网络透传/远程串口（需本地部署，见下方说明）
• 蓝牙 BLE — Web Bluetooth API，UUID16 / 完整 UUID，TX/RX 双特征

关键词染色 + 提取

• 填「起始 + 结束」→ 区间模式：染色该区间 + 提取区间内容
• 只填「起始」→ 关键词模式：高亮关键词 + 提取出现时间
• Text / HEX 双模式匹配，提取结果自动锁存，不被新数据挤丢

专业调试细节

• 显示：文本 / HEX / 同窗（文本|HEX 左右对照），Tab 一键切换
• 三折叠：左侧栏、右侧栏、发送区都可折叠，整个应用能缩成一个小窗口，不占地方
• 流控：DTR / RTS 手动控制，连接前可预置初始状态
• 智能自动滚动：检测到你在底部才跟随，上翻历史不被拉扯
• 大数据量优化：历史日志按块管理，默认只渲染最近区块，上滚动态加载更早历史、回到底部自动卸载，数据量再大内存与渲染也保持有界、不卡顿
• 收发：定时发送、文件发送（RAW / YModem）、快捷发送列表
• 管理：缓冲区保护、导出 TXT/BIN、一键复制、配置导入导出、清屏

⌨️ 快捷键

• Tab — 切换显示模式（文本 / HEX / 同窗）
• p — 连接 / 断开
• c — 清屏
• Ctrl+Enter / Cmd+Enter — 发送
• [ / ] — 折叠/展开左右侧栏
• ' — 折叠/展开发送区

🛠 快速开始

npm install
npm run dev      # 本地开发
npm run build    # 生产构建，部署 dist/ 目录即可

⚠️ 注意

• 串口 / 蓝牙要求 HTTPS 或 localhost（浏览器安全限制）
• WebSocket 模式需本地部署：页面在 HTTPS 下只能连安全的 wss://；要连普通 ws:// 本地/局域网服务，请把本工具跑在 localhost 上（npm run dev 或 npm run build 后本地托管）
• 建议使用 Chrome / Edge

背景

STM32L4低功耗开发中，临时关闭再重启GPIO中断时，常会出现无外部信号却自动触发中断的问题，会导致设备误唤醒、计数异常、低功耗逻辑出错。

IO中断传递链路

STM32L4中断传递链路：GPIO电平变化 → EXTI_IMR源头过滤 → 置位EXTI_PR挂起标志 → NVIC_ISER总开关放行 → CPU响应中断

其中PR标志置位后不会自动清零，会持续保存中断记录

误触发原因

1. HAL库关闭GPIO中断仅关闭NVIC_ISER内核总开关，只屏蔽中断上报，不会停止EXTI信号检测、不会清空PR挂起标志
2. 中断关闭期间，引脚电平抖动、电源瞬变产生的信号会留存PR残留标志
3. 重启中断开关后，残留标志会立即触发一次无效中断

解决方案

1. 重启NVIC中断前手动清空EXTI_PR挂起位，可消除历史残留，适配所有STM32芯片，兼容性最优；
2. 直接关闭EXTI_IMR屏蔽位，依托STM32L4芯片IMR前置、PR后置的硬件特性，从源头拦截信号，避免产生挂起残留。

部分STM32芯片链路为PR前置、IMR后置，仅关闭IMR无法清除已有残留，仍会出现误触发。因此代码跨芯片移植时，优先采用清PR挂起位的通用方案

ChaCha20 是什么

ChaCha20 是一种流密码（stream cipher），RFC 8439 标准。它是 TLS 1.3、QUIC、WireGuard 等新一代协议的默认加密算法之一，Google 在移动端全面用它替代 AES。和 AES 不同，它不需要硬件加速器，纯软件就能在 MCU 上高效运行。

核心特性：

• 对称加密：加密和解密是同一个操作（XOR 密钥流），调用同一个函数
• 无对齐要求：数据不需要 4 字节对齐，任意长度都能处理
• 资源友好：Cortex-M0+ 上 -Os 编译仅占约 700 字节 Flash，约 200 字节栈
• 输入参数：32 字节密钥 + 12 字节 nonce（同一密钥下 nonce 不能重复）

在 PY32F002A 上的用法

结合之前移植的 FlashStore A/B 分区存储，把 ChaCha20 作为加密层叠加在上面：

保存: 明文 → ChaCha20 加密 → FlashStore_Save → 写入 Flash
加载: FlashStore_Load → 密文 → ChaCha20 解密 → 明文

核心代码三行：

chacha20_crypt(data, size, key, nonce);   // 加密（或解密，同一函数）
FlashStore_Save(&cfg, data, size);        // 存到闪存
FlashStore_Load(&cfg, data, size);        // 读回
chacha20_crypt(data, size, key, nonce);   // 解密

实测：加密一句名言

用 "Stay hungry, stay foolish." 做测试，32 字节密钥 + 12 字节 nonce。

明文：

53 74 61 79 20 68 75 6e 67 72 79 2c 20 73 74 61  │Stay hungry, sta
79 20 66 6f 6f 6c 69 73 68 2e 00 00 00 00 00 00  │y foolish.......

加密后 — 完全不可读：

3a 28 1d a0 11 62 cd 14 4a 03 07 03 93 67 63 73  │:(...b..J....gcs
69 d1 59 2f a1 dd 95 06 2d 14 b5 28 29 ee 9f 0a  │i.Y/....-..()...

FlashStore 存盘再读回，解密还原 — 一字不差。

资源占用

PY32F002A（Cortex-M0+，48MHz，-Os）：

如果只需要存储不需要加密，去掉 ChaCha20 即可，约 800 字节搞定。

完整源码

只有 100 行，零依赖，复制到任何 MCU 项目即可使用。

#include "chacha20.h"
#include <string.h>

#define QR(a, b, c, d) do {          \
    (a) += (b); (d) ^= (a);           \
    (d) = ((d) << 16) | ((d) >> 16);  \
    (c) += (d); (b) ^= (c);           \
    (b) = ((b) << 12) | ((b) >> 20);  \
    (a) += (b); (d) ^= (a);           \
    (d) = ((d) << 8)  | ((d) >> 24);  \
    (c) += (d); (b) ^= (c);           \
    (b) = ((b) << 7)  | ((b) >> 25);  \
} while (0)

static uint32_t ld32(const uint8_t *p) {
    uint32_t v;
    memcpy(&v, p, sizeof(v));
    return v;
}

static void st32(uint8_t *p, uint32_t v) {
    memcpy(p, &v, sizeof(v));
}

static void chacha20_block(uint8_t out[64], const uint32_t init[16]) {
    uint32_t x[16];
    memcpy(x, init, sizeof(x));

    for (int i = 0; i < 10; i++) {
        QR(x[0], x[4], x[ 8], x[12]);
        QR(x[1], x[5], x[ 9], x[13]);
        QR(x[2], x[6], x[10], x[14]);
        QR(x[3], x[7], x[11], x[15]);
        QR(x[0], x[5], x[10], x[15]);
        QR(x[1], x[6], x[11], x[12]);
        QR(x[2], x[7], x[ 8], x[13]);
        QR(x[3], x[4], x[ 9], x[14]);
    }

    for (int i = 0; i < 16; i++)
        st32(out + i * 4, x[i] + init[i]);
}

void chacha20_crypt(uint8_t *data, size_t size,
                    const uint8_t key[32], const uint8_t nonce[12]) {
    if (size == 0) return;

    uint32_t state[16];
    state[0] = 0x61707865u;
    state[1] = 0x3320646eu;
    state[2] = 0x79622d32u;
    state[3] = 0x6b206574u;

    for (int i = 0; i < 8; i++)
        state[4 + i] = ld32(key + i * 4);

    state[12] = 1;

    for (int i = 0; i < 3; i++)
        state[13 + i] = ld32(nonce + i * 4);

    uint8_t keystream[64];
    size_t offset = 0;

    while (offset < size) {
        chacha20_block(keystream, state);

        size_t chunk = size - offset;
        if (chunk > 64) chunk = 64;

        for (size_t i = 0; i < chunk; i++)
            data[offset + i] ^= keystream[i];

        offset += chunk;
        state[12]++;
    }
}

头文件：

#ifndef CHACHA20_H
#define CHACHA20_H

#include <stddef.h>
#include <stdint.h>

void chacha20_crypt(uint8_t *data, size_t size,
                    const uint8_t key[32], const uint8_t nonce[12]);

#endif

A/B 双页 Flash 存储，面向小型 MCU。零依赖，无状态。

https://github.com/createskyblue/flashstore-ab-partition

选哪个？

资源占用（Cortex-M0 -Os 实测）

flash_store 明细：Load 158B / load_page 108B / save_page 100B / Save 66B / CRC32 52B / MaxDataSize 16B。按需链接，不用就不占。

5 分钟接入

1. 复制 include/flash_store.h、src/flash_store.c。需要加密再加 chacha20 或 xxtea
2. 实现 3 个回调：

bool my_read(void *ctx, uint32_t addr, uint8_t *out, size_t len) {
    memcpy(out, (void *)(uintptr_t)addr, len);  // 或 HAL 读
    return true;
}
bool my_erase(void *ctx, uint32_t addr, size_t len) {
    HAL_FLASH_ErasePage(addr);                  // 整页擦除
    return true;
}
bool my_program(void *ctx, uint32_t addr, const uint8_t *data, size_t len) {
    // 按 word 编程，或 memcpy（支持字节寻址的 flash）
    return true;
}

3. 初始化并读写：

FlashStore_IO io = {
    .read = my_read, .erase = my_erase, .program = my_program,
};
FlashStore_Config cfg = {
    .io = &io, .page_a_address = 0x0800FE00, .page_b_address = 0x0800FE80,
    .page_size = 128,
};
FlashStore_Save(&cfg, data, len);   // 写
FlashStore_Load(&cfg, data, len);   // 读

需要加密？推荐 ChaCha20——RFC 8439 标准，流密码不分块不要求对齐。实测 Cortex-M0 -Os：700B Flash + ~200B 栈，0 静态 RAM。极致省资源用 XXTEA，仅混淆级别，要求 4 字节对齐且 ≥8 字节。加密在外部做：encrypt → FlashStore_Save / FlashStore_Load → decrypt。

为什么不会丢数据

A 写完才写 B。 任意时刻断电，至少一份完整数据在 flash 上。

Save:  A 先 → B 后     Load: 读两页 → CRC 验 → 返回好的 → 顺手修坏的