TechBlog

Appearance

MAVLink 字段类型：wire 上是 uint8，语义上也可能是负数 ​

协议调试里，一个常见争论是：字段在生成的 C struct 中是 uint8_t，那它是不是只能表示 0–255？如果字段注释写的是 dBm，业务又希望传 -67 dBm，应该改 XML 类型吗？

答案要分成 wire representation 与 semantic interpretation 两层。

一个字节可以承载 signed 语义 ​

假设发送端把 -67 按 int8_t 表示，再放进一个 byte：

cpp
int8_t dbm = -67;
uint8_t wire = static_cast<uint8_t>(dbm);

接收端恢复：

cpp
int8_t dbm = static_cast<int8_t>(message.wifi_rssi);
printf("RSSI: %d dBm\n", static_cast<int>(dbm));

在二进制补码语义下，wire 上仍然只是 8 个 bit。uint8_t 可以作为 byte container，业务层再按 int8_t 解释。

但这个约定必须出现在字段描述、发送路径和接收路径中。只看生成 struct 的 C 类型，无法得到完整业务语义。

为什么不要随意把 XML 从 uint8 改成 int8 ​

MAVLink 的消息定义会参与生成代码和协议兼容。改变字段类型不只是本地变量重命名，可能影响 field ordering、生成 API、CRC_EXTRA 或下游库兼容性。

排查字段语义时，应同时检查：

  1. dialect XML；
  2. 生成头文件与字段注释；
  3. sender 的 encode/pack；
  4. 中间 router/enrich 路径；
  5. receiver 的 decode 与展示。

如果现有协议已经把该 byte 定义为 uint8_t 容器，并在注释中明确单位为 dBm，接收端按 int8_t 还原往往比修改 wire contract 更安全。

MAVLink 2 的 extension 字段位于 base fields 之后，可以向后兼容地追加。它们有两个重要特性：

  • extension 按 XML 声明顺序放在 payload 尾部；
  • payload 尾部的零字节可以被截断，实际 msg.len 可能短于完整 struct。

因此，“消息类型正确”不等于 extension 一定存在。路由器补字段时需要先判断原始消息长度是否已经包含扩展区：

cpp
if (msg.len > MESSAGE_MIN_LEN) {
    // 只在输入原本带 extension payload 时补扩展字段
}

否则，原本的 base-only 消息会被无意扩成长消息，改变带宽和下游语义。

Base 与 extension 的回归测试 ​

对自定义消息至少准备两组测试：

Base-only ​

  • 输入长度等于 MIN_LEN；
  • 路由后仍保持 MIN_LEN；
  • extension 解码为默认值；
  • 不因为“补充信息”而扩展 payload。

Extended ​

  • 输入长度大于 MIN_LEN；
  • extension 字段按约定更新；
  • encode → route → decode 后值一致；
  • 老版本接收端仍能读取 base fields。

一条可复用的判断原则 ​

协议字段问题不要只问“这个 C 类型是什么”，而要依次回答：

text
wire 上占几位？
业务单位和有效范围是什么？
发送端怎样编码？
接收端怎样解释？
消息长度是否真的包含该字段？
修改 schema 会不会改变兼容性？

MAVLink 官方文档对 payload 排序、截断、CRC_EXTRA 与 extension 规则有完整说明，可参考 Packet Serialization 和 Defining XML Messages。