本来没打算写这篇。上周帮一个做毕业设计的朋友看代码，他拿STM32F407做了个温湿度采集器，PC端上位机走串口通信。他用的还是最原始的办法：定义结构体，memcpy到数组后发出去，上位机再按偏移量一个一个字节地解析。加一个字段就要动协议、动上位机、动解析函数，一个下午全耗在改格式上了。后来我直接把工程切到 nanopb 协议传输，从写 proto 文件到两边编译跑通，前后不到十分钟。他当时问了句：你怎么做到改个协议就跟喝水一样快？于是就有了这篇文章。
这篇文章不追求讲全 protobuf 的每个特性，只讲清楚三件事：为什么在 STM32 这种资源受限的 MCU 上要选 nanopb、怎么把一个 .proto 文件变成可运行的 C 代码、以及串口链路上收发两端完整怎么写。文里所有的代码都是我实际在 F103 和 F407 上跑过的，你可以直接抄。
1. 为什么STM32上的协议传输，我最终选了nanopb而不是自研结构体或JSON
1.1 结构体直接发的翻车经历
很多从单片机入门走过来的朋友，第一个能跑通的通信方案都是这样的：
struct sensor_data { uint8_t type; uint16_t value; uint32_t timestamp; }; struct sensor_data data; data.type = 0x01; data.value = 256; data.timestamp = 1234567890; uint8_t buf[64]; memcpy(buf, &data, sizeof(data)); HAL_UART_Transmit(&huart2, buf, sizeof(data), 100);这段代码在 STM32 和 STM32 之间通信没出问题，但一旦对端换成 PC、换成 Linux 网关、换成 ESP8266 模块透传上位机，问题就开始往外冒。
第一个坑是字节对齐。C 结构体默认按 4 字节对齐，type占 1 字节后，value前面会补 1 个字节的 padding。如果你在 Keil 里没注意对齐设置，PC 端用 Python 的struct.unpack解析时偏移量就是错的，读出来的value是乱的。你说加#pragma pack(1)，那客户端和服务端所有平台都得跟着改，改漏一个就完蛋。
第二个坑是大小端。STM32 默认小端，PC 的 x86 也是小端，所以两头常年相安无事。可一旦协议要跑在某个大端平台上，你 memcpy 出去的多字节字段全部要重新排字节序。自研协议到这一步，排查成本就开始失控了。
第三个坑是版本演进的痛苦。设备端加一个字段，上位机解析函数就得跟着改；上位机加一个字段，设备端打包函数也得跟着改。两边结构体稍微不同步，线上就是数据错乱或者直接解析失败。这种问题还特别难复现，因为不是每次通信都用到新增字段。
我经历过一次之后，就给自己定了个规矩：凡是跨越 MCU 和上位机、MCU 和云端的通信，不再用"结构体+memcpy"这种原始方案，统一走协议描述文件。这也是为什么后来一接触 nanopb，就再也没回去过。
1.2 nanopb和JSON、自研协议的真实对比
先摆结论：在 STM32 上做数据序列化，主流方案就三条路——自研二进制协议、JSON、protobuf/nanopb。三条路我都写过线上产品，说下各自的体感。
| 对比维度 | 自研结构体+字节流 | JSON（cJSON） | nanopb |
|---|---|---|---|
| 开发速度 | 前期快，后期改协议很痛苦 | 快，但联调时字段名容易写错 | 改 proto 重新生成，全链路同步 |
| 协议可读性 | 差，全靠代码注释 | 好，肉眼可读 | 一般，需要配合 .proto 文件阅读 |
| Flash/RAM 占用 | 极低 | 中等，cJSON 内核加动态内存 | 极低，无动态内存分配 |
| 带宽开销 | 最小 | 大，Key 名重复占用字节 | 小，字段编号编码后很紧凑 |
| 跨平台兼容 | 差，对齐/大小端自己管 | 好 | 好，wire format 标准化 |
| 版本扩展 | 靠人肉同步，容易漏 | 容易，但老代码兼容要自己写 | 字段编号机制天然支持向后兼容 |
JSON 在 PC 上很好用，但在 STM32 上要慎重。一个简单的 JSON 字符串{"temp":25.6,"hum":65.8}光 Key 名就占掉十几个字节，MCU 带宽本身就金贵，不值得。更关键的是 cJSON 解析需要动态分配内存，F103 这种只有 20KB RAM 的芯片，跑几个嵌套对象就容易内存碎片。
nanopb 是 protobuf 在 C 语言下的精简实现，专为嵌入式设计。它和完整版 protobuf 的区别在于：不需要动态内存分配，所有内存占用在编译期就能算清楚；生成的代码全是纯 C，放在任何 STM32 工程里都能编译；核心代码只有几千字节级别。你写一个 .proto 文件，PC 端生成 C#/Python 代码，STM32 端生成 C 代码，两边的数据结构天然一致。这就把我最头疼的"两边同步"问题从代码层面消灭了。
1.3 一句话判断你的项目适不适合用它
我的经验是这样判断的：如果通信只发生在同一个板子内部的两个芯片之间，比如 STM32 和蓝牙模块之间，而且数据格式永远不变，那你用结构体裸发完全没问题，省事。但只要你需要和上位机、手机 App、云平台、或者其他团队维护的设备打交道，协议就一定会变，这时候直接上 nanopb。
另一个判断维度是消息体复杂度。如果只有一两个字节的状态开关，没必要上 nanopb，直接发一个字节就完了。但如果一条消息里有设备 ID、时间戳、多个传感器数值、报警标志、配置参数，这已经是典型的结构化消息，用 nanopb 整理一遍，收益非常大。
顺着这个思路往下，接下来就是动手了。下面我从环境准备开始，给你一条能直接跑通的完整路径。
2. 跑通前的三件套：环境、proto文件、生成的C代码
2.1 环境准备里最容易出错的一环
nanopb 涉及的工具有两个：protobuf 编译器protoc和 nanopb 的代码生成插件。很多人卡在第一步就是因为版本没配对。
我目前常用的组合是：protobuf 3.21.x + nanopb 0.4.8。这两个版本搭配非常稳定，生成的代码风格也一致。
安装方式不复杂。Linux 下直接：
sudo apt install protobuf-compilerWindows 下就麻烦一点。去 protobuf 的 GitHub releases 页面下载protoc-3.21.x-win64.zip，解压后把bin目录加进系统 PATH。然后下载 nanopb 源码包，解压到任意目录，比如D:\nanopb-0.4.8。
nanopb 官方推荐两种生成方式，我习惯用 nanopb 自带的生成脚本：
# Linux / macOS python nanopb/generator/nanopb_generator.py sensor.proto # Windows，注意是 nanopb/generator/protoc-gen-nanopb.bat protoc --nanopb_out=. sensor.proto --plugin=protoc-gen-nanopb=nanopb/generator/protoc-gen-nanopb.bat如果你是第一次配环境，我建议先在 PC 上把这一步跑通再挪到工程里。生成成功后会多出两个文件：sensor.pb.h和sensor.pb.c，看到这两个文件就说明环境没问题。
这里有个容易被忽略的坑：生成脚本依赖 Python 环境，而且 nanopb 0.4.x 需要 Python 3.6 以上。如果执行时报No module named grpc_tools之类的错误，多半是 Python 版本太老或缺少依赖，要么升级 Python，要么直接在 protoc 命令后面指定 nanopb 插件路径，后者不需要 Python。
2.2 一个最小可用的proto文件，连语法带注释
.proto 文件是协议的唯一事实来源。我写协议的风格是：能少写就少写，字段编号从 1 开始，必须给每个字段加注释，单位标注清楚。下面是一个完整的传感器上报协议：
syntax = "proto2"; message SensorData { required uint32 device_id = 1; // 设备ID，1~255 optional int32 temperature = 2; // 温度，单位 0.01℃ optional uint32 humidity = 3; // 湿度，单位 0.01%RH optional bool battery_low = 4; // 低电量告警 }这里我故意用 proto2 而不是 proto3，有两个原因。
一是 proto2 的optional字段会生成对应的has_temperature这样的标志位，解码的时候能判断"这个字段到底有没有出现在字节流里"。proto3 里所有字段都是 optional，但没有 has 标志，新手拿它判断"字段是否存在"会踩坑。
二是 proto2 里的required和optional语义更直观，适合刚上手时理解 protobuf 的字段存在性概念。实际项目里我不推荐用required，原因后面会专门讲。
字段编号是 protobuf 的核心机制。编码时不会传字段名，只传编号加类型，所以字段名随便改都不影响线上兼容，但字段编号一旦发布就不能变。这就是为什么说 protobuf 天然支持协议演进。
如果你要传可变长数组、字符串这类数据，需要额外配一个.options文件：
SensorData.desc max_size:32不配的话，生成的代码里 string/bytes 类型会变成pb_callback_t回调模式，处理起来很绕。配了max_size才会生成定长的char数组或uint8_t数组，在 MCU 上直接赋值就行。这一点官方文档写得隐晦，新手几乎都会卡一次。
2.3 生成代码后，你手里多了什么
执行完生成命令，打开sensor.pb.h，你会看到一个结构体和一张字段表。结构体长这样：
typedef struct _SensorData { uint32_t device_id; bool has_temperature; int32_t temperature; bool has_humidity; uint32_t humidity; bool has_battery_low; bool battery_low; } SensorData;has_xxx就是 proto2 里 optional 字段的存在标志。编码时，你把这个标志置 1，字段才会写进字节流；解码时，你对端如果没填这个字段，has_xxx就是 0，代码逻辑里就能安全跳过。
字段表是另一个关键东西：
extern const pb_field_t SensorData_fields[5];这张表就是 protobuf 编码和解码时的"规则字典"，里面记录了每个字段的编号、类型、在结构体里的偏移量。pb_encode和pb_decode就是拿着这张表，把结构体转成字节流、把字节流转回结构体。这张表是自动生成的，你千万不能手动改，改了一个字节对齐就对不上。
拿到这两个文件后，把它们和 nanopb 源码里的pb.h、pb.c、pb_common.h、pb_common.c、pb_encode.h、pb_encode.c、pb_decode.h、pb_decode.c一起加进 STM32 工程。Keil 里就是把文件加进分组，Include 路径指向 nanopb 源码目录。CubeMX 建的工程和标准库建的工程都不影响，nanopb 是纯 C 源码，编译环境只要是 C99 就够。
顺带提醒一句：Keil MDK 老版本默认按 C90 编译，nanopb 源码里用了 inline 等 C99 特性，编译会报错。解决办法是工程选项里把 C 标准切到 C99，或者直接用 AC6 编译器。这个问题在 STM32 论坛上被问过无数次，基本都是这个原因。
3. 弄懂Stream、Encode、Decode三个概念，后面代码就顺了
3.1 为什么接口是"流"而不是"Buffer"
第一次看 nanopb 的 API，很多人会疑惑：为什么不直接来个pb_encode(buffer, len, data)这种简单函数，非要搞个pb_ostream_t流对象？
设计流的目的，是为了让编码和解码的对象不局限于内存 buffer。你的数据可能很大，大到不能一次放进 RAM；你的发送目标可能是串口、SPI、以太网网卡，而不是一个内存数组。流对象把"往哪写"这个动作抽象出来了——你给它一个回调函数，它每编码一段字节就通过回调送出去一段。
在实际 STM32 项目里，90% 的场景还是用内存 buffer 就够了，所以 nanopb 提供了两个便捷初始化函数：
pb_ostream_from_buffer(buffer, size)：在内存 buffer 上建立输出流pb_istream_from_buffer(buffer, size)：在内存 buffer 上建立输入流
这两个函数返回一个pb_ostream_t或pb_istream_t，直接用就行。真正用到回调流的地方，是大消息、或者你不想为编码分配一块大 buffer 时。比如串口发送，直接把编码回调指向HAL_UART_Transmit，边编边发，省一块中转 buffer。这种写法在内存紧张的 F103 上有实际价值。
3.2 调用pb_encode之前要做什么
pb_encode的函数签名是：
bool pb_encode(pb_ostream_t *stream, const pb_field_t fields[], const void *src_struct);编码前有两件事必须做：用_init_default或_init_zero初始化结构体、给需要的字段赋值并设置has_xxx标志。
初始化特别容易被忽略。结构体是栈上变量，不初始化就是随机值。如果你某个字段忘了赋值，编码发出去的可能是垃圾数据。我见过一次线上 bug，设备 ID 偶尔变成 0，就是结构体没初始化、乱码叠加的结果。
正确做法：
SensorData msg = SensorData_init_default; msg.device_id = 0x01; msg.temperature = 256; // 25.6℃ msg.has_temperature = true; msg.humidity = 658; // 65.8%RH msg.has_humidity = true;has_xxx只对 optional 字段需要赋值。编码完成后，检查返回值。返回true表示成功，可以从stream.bytes_written拿到编码后的字节长度。返回false时，stream.errmsg会指向一个错误描述字符串，这是排查问题最直接的抓手。
3.3 解码时最容易迷惑的字段存在性问题
pb_decode的签名和 encode 对称：
bool pb_decode(pb_istream_t *stream, const pb_field_t fields[], void *dest_struct);解码前同样用_init_default初始化目标结构体，然后传入 buffer 流和字段表，函数内部会按照字段编号逐个读取字节流并填充结构体。
回到为什不用required这个问题上。proto2 的required字段如果在对端字节流里缺失，pb_decode会直接返回false并且报错。看起来是好事，对吧？但实际项目里这就成了扩展性的死穴：
假设第一版协议里device_id是 required，设备已经批量上线。第二版你想去掉 device_id，改成自动分配——老设备还在发 device_id，新设备不发了，旧版上位机在解码新设备数据时就会直接失败。而如果一开始用 optional，新设备不发 device_id，旧上位机解出来has_device_id = 0，代码里兜底处理就行，完全不影响整包解析。
所以我的建议很明确：线上协议能不用 required 就不用。字段缺失与否用 has 标志判断，这样老设备新设备才能自由混跑。
4. 完整可复现的串口收发示例：传感器上报 + 配置下发
4.1 场景设定：F103采集 + 上位机下发配置
这一节给一个可以直接搬到工程里的完整闭环：STM32 通过串口每隔 1 秒上报温湿度数据，上位机给 STM32 下发一条电机配置帧，MCU 解码后更新全局变量。
用到的 proto 文件，除了前面的 SensorData，再加一个配置帧：
syntax = "proto2"; message MotorConfig { optional uint32 target_speed = 1; // 目标转速，rpm optional bool enable = 2; // 使能 }命令重新生成后，工程里会有sensor.pb.c/h和motor_config.pb.c/h两组文件。把它们全部加入 Keil 工程，Include 路径记得加 nanopb 源码目录。
4.2 发送端完整代码
发送端直接上代码，串口用的 HAL 库，假设huart2已经初始化好：
#include "sensor.pb.h" #include "pb_encode.h" #include "usart.h" uint8_t g_encode_buf[64]; void SendSensorData(void) { SensorData msg = SensorData_init_default; msg.device_id = 0x01; msg.temperature = 256; /* 25.6℃ */ msg.humidity = 658; /* 65.8%RH */ msg.battery_low = false; msg.has_temperature = true; msg.has_humidity = true; msg.has_battery_low = true; pb_ostream_t stream = pb_ostream_from_buffer(g_encode_buf, sizeof(g_encode_buf)); if (pb_encode(&stream, SensorData_fields, &msg)) { HAL_UART_Transmit(&huart2, g_encode_buf, stream.bytes_written, 100); } else { /* 编码失败，stream.errmsg 里有原因 */ } }主循环里直接调用SendSensorData()再HAL_Delay(1000)就行。编码结果最多十几个字节，g_encode_buf开 64 字节绰绰有余。
4.3 接收端完整代码
接收端稍微复杂一点，这里给出核心解码函数。假设你的串口接收中断已经把一帧数据收进了g_rx_buf，帧长度存在g_rx_len：
#include "motor_config.pb.h" #include "pb_decode.h" uint8_t g_rx_buf[64]; uint16_t g_rx_len = 0; void ProcessRxConfig(void) { MotorConfig cfg = MotorConfig_init_default; pb_istream_t stream = pb_istream_from_buffer(g_rx_buf, g_rx_len); if (pb_decode(&stream, MotorConfig_fields, &cfg)) { if (cfg.has_target_speed) { g_target_speed = cfg.target_speed; } if (cfg.has_enable) { g_motor_enable = cfg.enable; } } else { /* 解码失败，stream.errmsg 里有原因 */ } }需要注意，pb_istream_from_buffer不会拷贝数据，它只是把缓冲区地址记录在流对象里。所以g_rx_buf的内容必须在pb_decode执行完之前保持有效。如果你的串口中断会持续往g_rx_buf里写新数据，一定要等pb_decode返回后再允许接收下一帧。
这就是我在实际项目里采用"主循环集中处理、接收中断只负责搬运"的原因。串口中断里解码看起来省事，但一旦数据帧还没收全、或中断和主循环同时访问g_rx_buf，就会出非常难查的偶发问题。
4.4 "5分钟"的真实时间账单
标题说 5 分钟，前提是环境已经配好、工程已经能跑串口。在这个前提下，改一个字段并全链路跑通的真实时间分配是这样的：
| 操作 | 熟练后耗时 |
|---|---|
| proto 文件加一个字段 | 30秒 |
| 重新生成 C 代码 | 30秒 |
| 发送/接收代码里填充或读取该字段 | 1~2分钟 |
| 编译烧录、串口助手验证 | 1分钟 |
加起来确实在 5 分钟上下。核心思路是：协议变更的"改代码"环节，被压缩到只剩"结构体字段赋值"和"结构体字段读取"两个动作。剩下的都由代码生成器自动完成。这就是 nanopb 最值钱的地方。
5. 实战趟过的坑，以及F103上实测的耗时与内存数据
5.1 字段扩张与协议兼容性，坑在"自作聪明"
项目上线跑了一阵后，你多半会加字段。protobuf 的字段编号机制决定了：新增可选字段不会破坏老设备通信。但有个前提——不能修改老字段的编号和类型。
我踩过的一个坑是这样的：第一版协议里temperature是int32，单位 0.01℃。后来想提高精度，把字段类型从int32改成int64。结果跑上线，老设备发来的 4 字节温度，新上位机按 8 字节解读，整个字段错位，后续字段全乱。
后来老老实实加了一个新字段high_prec_temp，老字段保留但不使用，新老设备才平稳共存。所以我的经验是：协议字段只能追加，不能修改。真要废弃旧字段，就保留编号、把名称改成deprecated_xxx，不要删除定义。
5.2 串口是字节流，nanopb不负责粘包和半包
很多初学朋友把 pb_encode 出来的字节直接往串口发，对端也用pb_istream_from_buffer直接解，结果发现偶尔解析失败。原因很简单：nanopb 只负责把结构体序列化成字节流，不负责告诉你一帧从哪里开始、到哪里结束。
串口是纯字节流，如果发送端连续发两条消息，接收端必须自己切分帧边界。我常用的简易帧格式：
帧头(0xAA 0x55) | payload长度(1字节) | payload | CRC8(1字节)payload 就是 pb_encode 出来的字节流。接收端先找帧头，再按长度收 payload，CRC 校验通过后再交给 pb_decode 解析。这套状态机很简单，但能解决 90% 的粘包半包问题。
如果走以太网或者和有良好分包机制的链路通信，可以省掉自定义帧头，但 CRC 或校验和不要省。串口场景下环境干扰、波特率误差都可能导致字节错位，没有校验，错误会被上层静默吞掉。
5.3 大小端和float精度，跨平台前要先想清楚
protobuf 的 wire format 里，多字节整数按小端编码。STM32 全系列默认小端，和 protobuf 天然对齐，所以单片机内部通信基本不用管大小端。但如果你和某些 DSP、PowerPC 架构的网关通信，就要在协议层确认大小端匹配。
float 字段是另一个坑。protobuf 对 float 按 IEEE754 标准编码，这个没问题，问题出在两边精度不一致。我在一个项目里发现，STM32 端算出来 25.600000，PC 端解码后显示 25.599999，就是因为两边浮点运算精度差异。用于显示和控制没问题，但如果你拿它做精确比较，记得设一个合理的 epsilon。
如果你对精度有硬要求，一个通用的做法是像我在前面示例里那样：用整数表示定点数。比如温度用 int32，约定单位是 0.01℃，25.6℃ 就传 256。这样既避免 float 精度问题，也让日志和调试时看到的协议数据直观可读。
5.4 F103上实测：编码耗时几十微秒，内存占用几乎可以忽略
我在 STM32F103C8T6 上用 72MHz 主频，对前面那个 SensorData（4 个字段）做了实测：
| 指标 | 实测值 |
|---|---|
| pb_encode 耗时 | 约 30 微秒 |
| pb_decode 耗时 | 约 40 微秒 |
| 编码后字节长度 | 14 字节左右 |
| 编码临时 buffer | 64 字节 |
| nanopb 核心库 Flash 占用 | 约 4KB 左右 |
| 动态内存分配 | 无 |
70MHz 主频下，一次编解码总共不到 100 微秒，对于秒级上报的应用来说完全不是瓶颈。哪怕你要做 1kHz 的控制环，只要不是每个周期都编解码一整个复合消息，也扛得住。
核心库 4KB 的 Flash 占用，在 F103 的 64KB Flash 里占的比例很小。生成代码的字段表也就是几百字节级别。这也是我推荐 nanopb 的一个重要原因——性能、容量、内存三个维度都适合 MCU。
5.5 调试小技巧，官方文档里不太写但很好用
最后分享几个我日常调试 nanopb 时的小习惯。
第一，pb_encode或pb_decode返回false时，别急着看数据。先把stream.errmsg打印出来。它会直接告诉你类似 "field number 2 does not exist" 或 "wrong wire type" 这样具体的错误原因。这个信息能省掉你一半的抓瞎时间。
第二，PC 端先用 Python + protobuf 把协议跑通，再去调 STM32。步骤是：同样的 .proto 文件，PC 上生成 Python 代码，先模拟发送端和接收端，确认协议定义本身没问题；然后再把 STM32 接入。这样出了问题，你能快速定位是"协议定义错了"还是"MCU 代码写错了"，不用两头猜。
第三，工程管理上，把 .proto 和 .options 文件放进版本库，但生成出来的 .pb.c/.pb.h 不要提交到 git。每个开发者在本地用自己的工具链生成，避免不同版本的生成器互相覆盖导致 diff 灾难。
第四，如果你频繁改 proto 字段名，调试时发现对端解析异常，先确认两端的 .proto 文件是不是同一个版本。这种问题跟代码 bug 很像，实际就是协议版本不一致。在设备启动日志里打一个协议版本号，能帮你快速判断。
这些细节都不复杂，但都是我在实际项目中踩出来、一条一条记下来的。nanopb 本身已经很成熟，真正让人头疼的往往不是库本身，而是协议演进、帧边界、跨平台这些外围问题。把上面的坑避开，你基本可以放心地在 STM32 上长期使用它。
