PX4-Autopilot 中的 RadioStatus UORB 消息:遥测链路信号质量的完整字段解读与源码级实现剖析
PX4-Autopilot 中的 RadioStatus UORB 消息:遥测链路信号质量的完整字段解读与源码级实现剖析
导读
RadioStatus 是 PX4-Autopilot 中用于描述地面站与飞控之间遥测(Telemetry)无线电链路实时质量的标准 uORB 消息,其话题名为 radio_status。该消息由 MAVLink 通道接收到的 RADIO_STATUS 报文解码而来,承载本地/远端信号强度(RSSI)、发射缓冲区占用率(txbuf)、噪声水平、接收错误数等关键指标,并直接参与 PX4 的软件 MAVLink 节流(Software Throttling)机制。阅读本文后,你将掌握 RadioStatus 的每一个字段含义、其发布与消费的完整调用链,以及如何利用 MAV_x_RADIO_CTL 参数实现基于链路拥塞的自适应遥测速率控制。
一、消息概览与话题定义
在 msg/RadioStatus.msg 中,该消息被定义为 8 个字段的 uORB 结构体,消息头部携带 timestamp(自系统启动以来的微秒时间戳),正文为 5 个 uint8 类型的链路质量指标和 2 个 uint16 类型的统计计数:
uint64 timestamp # time since system start (microseconds)
uint8 rssi # local signal strength
uint8 remote_rssi # remote signal strength
uint8 txbuf # how full the tx buffer is as a percentage
uint8 noise # background noise level
uint8 remote_noise # remote background noise level
uint16 rxerrors # receive errors
uint16 fix # count of error corrected packets
该消息对应官方文档 docs/en/msg_docs/RadioStatus.md,其 TOPICS 声明为 radio_status,即发布者向该 uORB 话题发布数据时使用的主题名。所有字段均无单位标注,属于链路状态类型的归一化/百分比语义数据。
二、字段语义逐项解读
下表完整对应文档中的字段表,并结合典型遥测无线电(如 SiK/3DR 数传、Holybro Telemetry Radio 等)的行业惯例进行补充说明:
| 字段名 | 类型 | 语义说明 | 典型取值范围/惯例 |
|---|---|---|---|
timestamp |
uint64 |
时间戳,单位微秒(自系统启动起) | 0 至系统运行时长 |
rssi |
uint8 |
本地信号强度(飞控侧接收到的链路强度) | 0–100,越高越好 |
remote_rssi |
uint8 |
远端信号强度(地面站/数传模块侧接收强度) | 0–100,越高越好 |
txbuf |
uint8 |
发射缓冲区占用百分比,反映链路拥塞程度 | 0–100,越低越好 |
noise |
uint8 |
本地背景噪声水平 | 0–100,越低越好 |
remote_noise |
uint8 |
远端背景噪声水平 | 0–100,越低越好 |
rxerrors |
uint16 |
接收错误计数(累计丢包/错误帧) | 0–65535 |
fix |
uint16 |
被纠错修复的数据包计数 | 0–65535 |
其中 txbuf 是整个消息中控制语义最强的一个字段:它直接决定后续软件节流逻辑是否介入(详见第四节),因此也是 src/modules/mavlink/module.yaml 中 MAV_x_RADIO_CTL 参数文档所特别引用的字段。
三、源码级实现:从 MAVLink RADIO_STATUS 到 uORB radio_status
3.1 消息接收与解码
RadioStatus 在 PX4 中的唯一生产路径来自 MAVLink 的 RADIO_STATUS 报文。核心实现在 src/modules/mavlink/mavlink_receiver.cpp 的 MavlinkReceiver::handle_message_radio_status()(L1931-L1954):
void
MavlinkReceiver::handle_message_radio_status(mavlink_message_t *msg)
{
/* telemetry status supported only on first ORB_MULTI_MAX_INSTANCES mavlink channels */
if (_mavlink.get_channel() < (mavlink_channel_t)ORB_MULTI_MAX_INSTANCES) {
mavlink_radio_status_t rstatus;
mavlink_msg_radio_status_decode(msg, &rstatus);
radio_status_s status{};
status.timestamp = hrt_absolute_time();
status.rssi = rstatus.rssi;
status.remote_rssi = rstatus.remrssi;
status.txbuf = rstatus.txbuf;
status.noise = rstatus.noise;
status.remote_noise = rstatus.remnoise;
status.rxerrors = rstatus.rxerrors;
status.fix = rstatus.fixed;
_mavlink.update_radio_status(status);
_radio_status_pub.publish(status);
}
}
从这段实现可以得到三条重要事实:
- 字段映射关系:MAVLink 报文中的
remrssi、remnoise、fixed分别映射为 uORB 中的remote_rssi、remote_noise、fix,其余字段同名直传。timestamp并非取自报文,而是由hrt_absolute_time()在飞控本地生成。 - 通道限制:只有前
ORB_MULTI_MAX_INSTANCES个 MAVLink 通道的RADIO_STATUS会被处理,这是为了避免多路遥测链路同时上报时互相干扰状态统计。 - 双路输出:解码结果一方面通过
update_radio_status()交给 MAVLink 主模块做内部状态更新与节流计算,另一方面通过_radio_status_pub.publish(status)发布到radio_statusuORB 话题,供日志系统及其他模块订阅。
3.2 状态打印与调试
MAVLink 模块还提供了针对该话题的诊断输出。在 src/modules/mavlink/mavlink_main.cpp 的 status 打印逻辑中(L3420-L3439),若 radio_status_available 为真,会逐行输出:
rssi: <uint8>
remote rssi: <uint8>
txbuf: <uint8>
noise: <uint8>
remote noise: <uint8>
rx errors: <uint16>
fixed: <uint16>
这为地面站通过 NSH 控制台排查链路问题提供了直接依据。
四、核心应用场景:基于 txbuf 的软件 MAVLink 节流
RadioStatus 最有价值的工程用途是驱动 软件 MAVLink 节流(Software Throttling):当地面无线电链路拥塞时(表现为飞控侧发射缓冲区持续打满),PX4 会主动降低 MAVLink 消息发送速率,防止链路进一步恶化;链路空闲时再逐步恢复。该机制完全围绕 txbuf 字段展开。
4.1 阈值定义
阈值常量定义于 src/modules/mavlink/mavlink_main.h:
static constexpr unsigned RADIO_BUFFER_CRITICAL_LOW_PERCENTAGE = 25;
static constexpr unsigned RADIO_BUFFER_LOW_PERCENTAGE = 35;
static constexpr unsigned RADIO_BUFFER_HALF_PERCENTAGE = 50;
4.2 节流算法
核心计算位于 src/modules/mavlink/mavlink_main.cpp 的 Mavlink::update_radio_status()(L1582-L1612):
if (_use_software_mav_throttling) {
/* check hardware limits */
_radio_status_critical = (radio_status.txbuf < RADIO_BUFFER_LOW_PERCENTAGE);
if (radio_status.txbuf < RADIO_BUFFER_CRITICAL_LOW_PERCENTAGE) {
/* this indicates link congestion, reduce rate by 20% */
_radio_status_mult *= 0.80f;
} else if (radio_status.txbuf < RADIO_BUFFER_LOW_PERCENTAGE) {
/* this indicates link congestion, reduce rate by 2.5% */
_radio_status_mult *= 0.975f;
} else if (radio_status.txbuf > RADIO_BUFFER_HALF_PERCENTAGE) {
/* this indicates spare bandwidth, increase by 2.5% */
_radio_status_mult *= 1.025f;
}
/* Constrain radio status multiplier between 1% and 100% to allow recovery */
_radio_status_mult = math::constrain(_radio_status_mult, 0.01f, 1.0f);
}
算法要点归纳:
- txbuf < 25%(临界低值):链路严重拥塞,发送速率乘性降低 20%(×0.80)。
- 25% ≤ txbuf < 35%:轻度拥塞,速率降低 2.5%(×0.975)。
- txbuf > 50%:链路带宽充裕,速率提升 2.5%(×1.025)。
- 乘数
_radio_status_mult被约束在 0.01 ~ 1.0 之间,保证即使链路持续拥塞,仍有至少 1% 的速率用于维持心跳等关键消息,避免彻底失联。 - 同时
_radio_status_critical标志位被置位,供上层判断链路是否进入关键拥塞状态(radio_status_critical()访问器见 mavlink_main.cpp L1575-L1580)。
4.3 开关参数 MAV_x_RADIO_CTL
该节流机制由参数 MAV_${i}_RADIO_CTL(i 为 MAVLink 实例号)控制,定义于 src/modules/mavlink/module.yaml:
MAV_${i}_RADIO_CTL:
description:
short: Enable software throttling of mavlink on instance ${i}
long: |
If enabled, MAVLink messages will be throttled according to
`txbuf` field reported by radio_status.
Requires a radio to send the mavlink message RADIO_STATUS.
type: boolean
reboot_required: true
num_instances: *max_num_config_instances
default: [true, true, true]
实操要点:
- 参数类型为布尔型,修改后需要重启飞控生效(
reboot_required: true)。 - 默认值对前三个 MAVLink 实例均为
true,即默认开启软件节流。 - 前置条件:遥测无线电必须主动发送 MAVLink
RADIO_STATUS报文,否则radio_status话题没有数据源,节流逻辑不会触发。 - 每个 MAVLink 实例可独立配置,例如在以太网/UDP 链路(无 RADIO_STATUS 来源)上可关闭该实例的节流。
五、日志记录与地面站观测
radio_status 话题被默认纳入飞行日志记录范围。在 src/modules/logger/logged_topics.cpp 中可以看到:
add_topic("radio_status");
这意味着无需额外配置,每次飞行/测试的 ulog 中都会包含完整的链路质量时间序列。结合 docs/en/msg_docs/RadioStatus.md 的字段表,地面站软件(如 QGroundControl 的 Radio 状态面板)正是通过订阅该话题或直接解析 MAVLink RADIO_STATUS 来显示信号条、链路丢包率与缓冲区占用情况的。
排查链路问题的推荐步骤:
- 在 NSH 控制台运行
mavlink status,检查rssi/remote rssi/txbuf输出; - 若
txbuf长期处于高位(接近 100),说明链路带宽不足,应先降低 MAVLink 消息速率或检查干扰源,而非仅依赖软件节流兜底; - 若
rxerrors持续快速增长,表明链路上存在丢帧/错帧,需检查射频环境、天线连接与数传模块固件; - 用 Flight Review 等工具分析 ulog 中的
radio_status曲线,对比txbuf与各消息实际发送速率的变化关系,验证节流是否按预期工作。
六、总结
RadioStatus 虽然只是一个 8 字段的小型 uORB 消息,却是 PX4 遥测链路健康监测与自适应流控的枢纽:它通过 src/modules/mavlink/mavlink_receiver.cpp 从 MAVLink RADIO_STATUS 解码而来,由 src/modules/mavlink/mavlink_main.cpp 的 update_radio_status() 依据 txbuf 驱动发送速率乘数的升降,并通过 src/modules/mavlink/module.yaml 中的 MAV_x_RADIO_CTL 参数开关控制,最终由 src/modules/logger/logged_topics.cpp 默认记录进日志。理解这一消息的字段语义与调用链,是诊断数传链路问题、优化长距离遥测稳定性的基础。