单片机与物联网 / 系统课时

为协议写一份字段规范

为协议写一份字段规范

本篇把口头约定整理成可直接联调的字段规范:每个字节的偏移、长度、字节序、取值范围、校验范围、超时和错误码都有明确依据,发送端与解析端可以按同一张表实现。

学习目标

  • 能为一帧串口协议定义完整字段边界和编码规则。
  • 能明确校验、超时和错误码的判定条件。
  • 能用规范表支撑跨团队实现、抓包和故障定位。

先固定帧的整体规则

一份可执行的协议规范,第一步不是写字段名称,而是先说明“这一帧从哪里开始、到哪里结束”。下面以固定帧头 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、响应超时”各验证一次。字段表应让开发、测试和抓包人员得到同一个答案:从第几个字节开始读、读几个字节、按什么方式解释,以及异常时应如何处理。

最终,这份规范不是说明性的表格,而是实现契约。只要字段边界、编码规则、校验范围和失败行为都能被逐项验证,后续的串口程序、抓包分析和跨团队联调才能建立在同一份协议定义上。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为协议写一份字段规范

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通