单片机与物联网 / 系统课时
为协议写一份字段规范
为协议写一份字段规范
本篇把口头约定整理成可直接联调的字段规范:每个字节的偏移、长度、字节序、取值范围、校验范围、超时和错误码都有明确依据,发送端与解析端可以按同一张表实现。
学习目标
- 能为一帧串口协议定义完整字段边界和编码规则。
- 能明确校验、超时和错误码的判定条件。
- 能用规范表支撑跨团队实现、抓包和故障定位。
先固定帧的整体规则
一份可执行的协议规范,第一步不是写字段名称,而是先说明“这一帧从哪里开始、到哪里结束”。下面以固定帧头 AA 55、长度字段表示后续有效载荷长度为例。
假设帧结构如下:
| 字段 | 偏移 | 长度 | 编码规则 | 说明 |
|---|---|---|---|---|
| 帧头 | 0 | 2 字节 | 固定 AA 55 |
用于定位帧起点 |
| 版本 | 2 | 1 字节 | 无符号整数 | 当前协议版本 |
| 命令 | 3 | 1 字节 | 无符号整数 | 请求或响应类型 |
| 长度 | 4 | 2 字节 | 大端 | 后续有效载荷长度 |
| 载荷 | 6 | N 字节 | 按命令定义 | 业务数据 |
| 校验 | 6+N | 2 字节 | CRC-16 | 覆盖版本、命令、长度和载荷 |
这里最关键的是“偏移”和“长度”必须可以直接用于解析。如果长度字段占两字节,就不能只写“长度”,还要写清字节序;否则不同语言或不同芯片实现可能得到不同整数。
把取值范围写成机器可执行的规则
字段规范不能只描述类型,还要写出合法范围。例如版本可以规定 1 表示当前版本,命令 0x01 表示查询状态,0x02 表示设置参数。长度字段若最大允许 256,解析器就应在读完长度后立即检查边界。
建议把特殊值单独写明,例如 0x00 表示成功、0x01 表示参数错误。不要让“预留值”变成默认行为;对于未定义命令,协议应明确返回哪个错误码或直接丢弃。
明确校验范围和计算顺序
“使用 CRC-16”仍然不够,因为还缺少多项式、初始值、结果处理和覆盖范围。至少要说明校验从哪个偏移开始,到哪个字段结束。
本例中校验范围为偏移 2 到 5+N,也就是版本、命令、长度和载荷,不包含帧头,也不包含 CRC 本身。联调文档中最好再给出一个完整报文样例,让开发者能用抓包结果逐字节核对。
超时与错误码也属于协议的一部分
串口协议不仅规定字节格式,还要规定等待行为。例如发送一帧后,接收端在 <TIME> 毫秒内没有收到完整响应,可以判定为超时;收到帧头但长度字段声明的数据尚未到齐,则应继续等待,而不是立即按坏帧处理。
错误码应能区分至少三类问题:无法解析的报文、格式正确但参数非法、设备当前状态不允许执行。这样调用方才能决定重试、修正参数还是终止操作。
一个适合交付给联调团队的错误码表可以写成:
| 错误码 | 含义 | 发送条件 | 接收方处理 |
|---|---|---|---|
0x00 |
成功 | 请求已执行 | 继续处理响应 |
0x01 |
参数错误 | 字段值越界或格式非法 | 修正参数后重试 |
0x02 |
不支持命令 | 命令码未实现 | 不应重复发送同一命令 |
0x03 |
状态不允许 | 当前设备状态禁止操作 | 先改变设备状态 |
0x04 |
校验错误 | CRC 不匹配 | 丢弃当前帧 |
联调前做一次边界检查
规范真正落地前,至少拿“最短帧、最长帧、非法长度、非法命令、非法参数、错误 CRC、响应超时”各验证一次。字段表应让开发、测试和抓包人员得到同一个答案:从第几个字节开始读、读几个字节、按什么方式解释,以及异常时应如何处理。
最终,这份规范不是说明性的表格,而是实现契约。只要字段边界、编码规则、校验范围和失败行为都能被逐项验证,后续的串口程序、抓包分析和跨团队联调才能建立在同一份协议定义上。