PX4 uORB 消息解析:ActuatorTest(actuator_test)舵机/电机测试消息的字段、常量与全链路实现
PX4 uORB 消息解析:ActuatorTest(actuator_test)舵机/电机测试消息的字段、常量与全链路实现
本篇技术指南以 PX4 官方 uORB 消息文档 ActuatorTest.md 为骨架,完整讲解 actuator_test 话题的字段语义、常量定义与取值范围,并结合仓库内 消息源文件、actuator_test 命令行模块 与 混控器侧的 ActuatorTest 消费者,还原从"命令行下发指令"到"单个执行机构输出被覆盖"的完整调用链。读完本文,你能够理解该消息的设计动机,掌握 actuator_test 命令的实操用法,并能在自定义模块中正确发布或订阅该话题完成单通道执行机构测试。
消息定位:为什么要单独定义 actuator_test 话题
在 PX4 中,混控器(mixer)通常依据控制分配的结果驱动全部电机与舵机输出。但在调试、检修和电调校准(ESC calibration)场景下,我们需要绕过正常的飞行控制回路,对某一个具体的执行机构通道单独施加输出,例如:
- 逐一验证 8 个电机中某一路的转向与转速是否正确;
- 让某个舵机偏转到指定角度,检查机械行程与方向;
- 电调校准流程中向所有电机通道输出固定占空比;
- 验证自定义的输出函数(function)映射是否正确。
actuator_test 正是为此设计的 uORB 话题。它的注释明确写着"Topic to test individual actuator output functions"(用于测试单个执行机构输出函数的话题),其定义位于 msg/ActuatorTest.msg,由消息定义工具链生成 actuator_test_s 结构体与 actuator_test 话题 ID。发布该话题后,混控器模块(MixerModule)会截获并覆盖对应通道的输出值,从而实现脱离飞控回路的单通道控制。
消息字段:结构、类型与语义
actuator_test 消息共包含 5 个字段,如下表所示(与官方文档 ActuatorTest.md 的 Fields 章节一一对应):
| 字段 | 类型 | 说明 |
|---|---|---|
timestamp |
uint64 |
自系统启动以来的时间(微秒),由 hrt_absolute_time() 填充 |
action |
uint8 |
动作类型,取值为 ACTION_* 常量之一(见下文常量表) |
function |
uint16 |
目标执行机构的输出函数编号(actuator output function) |
value |
float32 |
输出值,取值范围 [-1, 1],详见下方取值语义 |
timeout_ms |
uint32 |
测试模式超时时间(毫秒),超时后自动退出测试模式;若为 0 表示不超时 |
value 字段的取值语义(核心)
value 字段虽然只是 float32,但其取值语义在消息源文件中注释得非常完整,这是理解本消息的关键:
1:最大正向输出(电机满油门 / 舵机满行程一端);0:舵机居中,或电机最小油门(minimum motor thrust);-1:最大负向输出(若执行机构不支持负值,例如普通单向电机,则<0会被映射为NaN);NaN:映射为"解除武装"(disarmed),即停止电机(NaN maps to disarmed (stop the motors))。
在 src/systemcmds/actuator_test/actuator_test.cpp 中,命令行对 value 做了硬校验:if (value < -1.f || value > 1.f) 时直接报错退出,确保发布到话题上的值始终落在 [-1, 1] 区间内。
timeout_ms 字段的双重角色
timeout_ms 用于在测试模式下设置自动退出时限:
- 若
timeout_ms > 0,消费端会记录一个绝对超时时刻_next_timeout = now + actuator_test.timeout_ms * 1000,超时后自动退出测试模式; - 若
timeout_ms == 0,则不超时,测试模式会一直持续到收到ACTION_RELEASE_CONTROL或所有通道都被释放。
从 src/systemcmds/actuator_test/actuator_test.cpp 可以看到,命令行在未指定 -t 参数时走的是交互模式:发布 ACTION_DO_CONTROL 后阻塞等待用户按 Enter,收到按键后再发布 value = NAN、ACTION_RELEASE_CONTROL 的释放消息退出测试模式。
常量表:动作类型与功能编号
官方文档的 Constants 章节定义了本消息的全部常量,它们是字段取值与功能映射的契约:
| 常量名 | 类型 | 值 | 说明 |
|---|---|---|---|
ACTION_RELEASE_CONTROL |
uint8 |
0 | 退出指定 function 的测试模式 |
ACTION_DO_CONTROL |
uint8 |
1 | 进入执行机构测试模式 |
FUNCTION_MOTOR1 |
uint8 |
101 | 电机 1 的功能编号起点 |
MAX_NUM_MOTORS |
uint8 |
12 | 最大电机数量 |
FUNCTION_SERVO1 |
uint8 |
201 | 舵机 1 的功能编号起点 |
MAX_NUM_SERVOS |
uint8 |
15 | 最大舵机数量 |
ORB_QUEUE_LENGTH |
uint8 |
16 | 话题队列长度,注释要求 >= MAX_NUM_MOTORS 以支持 esc_calibration 中的发布逻辑 |
功能编号(function)与输出函数的对应关系
function 字段使用的编号与混控器模块的输出函数定义严格对应。在 src/lib/mixer_module/output_functions.yaml 中可以看到完整的编号体系:
Motor: 起始编号 101,共 12 个(即FUNCTION_MOTOR1到FUNCTION_MOTOR1 + 11);Servo: 起始编号 201,共 15 个(即FUNCTION_SERVO1到FUNCTION_SERVO1 + 14);Peripheral_via_Actuator_Set: 起始 301,共 6 个;- 其它专用函数,如
Landing_Gear: 400、Parachute: 401、RC_Roll: 402、Gimbal_Roll: 420、Gripper: 430、IC_Engine_Ignition: 450等。
该 yaml 文件顶部特别注释"do not change the index of existing functions, as it will break existing setups using it"(不要修改已有函数的索引,否则会破坏既有配置),说明这些编号是长期稳定的公共契约。为了确保消息常量与混控器枚举不漂移,actuator_test.hpp 中还放置了 4 个编译期静态断言(static_assert),逐一校验 FUNCTION_MOTOR1 == OutputFunction::Motor1、MAX_NUM_MOTORS 与 MotorMax - Motor1 + 1 相等、FUNCTION_SERVO1 == OutputFunction::Servo1 等,任何一侧改动导致不一致都会直接编译失败。
ORB_QUEUE_LENGTH = 16 的用意
ORB_QUEUE_LENGTH 被设为 16,且注释要求 >= MAX_NUM_MOTORS(12)。原因可以在 src/modules/commander/esc_calibration.cpp 中找到:电调校准流程中 set_motor_actuators() 会在极短时间内连续发布最多 12 条消息(FUNCTION_MOTOR1 + i,i 从 0 到 11),若队列长度小于发布数量,较早的消息会被覆盖丢弃,导致部分通道收不到校准指令。16 的队列长度保证了这批突发消息可以被消费端完整接收。
消息源文件全貌
消息的权威定义位于 msg/ActuatorTest.msg,完整内容如下:
uint64 timestamp # time since system start (microseconds)
# Topic to test individual actuator output functions
uint8 ACTION_RELEASE_CONTROL = 0 # exit test mode for the given function
uint8 ACTION_DO_CONTROL = 1 # enable actuator test mode
uint8 FUNCTION_MOTOR1 = 101
uint8 MAX_NUM_MOTORS = 12
uint8 FUNCTION_SERVO1 = 201
uint8 MAX_NUM_SERVOS = 15
uint8 action # one of ACTION_*
uint16 function # actuator output function
float32 value # range: [-1, 1], where 1 means maximum positive output,
# 0 to center servos or minimum motor thrust,
# -1 maximum negative (if not supported by the motors, <0 maps to NaN),
# and NaN maps to disarmed (stop the motors)
uint32 timeout_ms # timeout in ms after which to exit test mode (if 0, do not time out)
uint8 ORB_QUEUE_LENGTH = 16 # >= MAX_NUM_MOTORS to support code in esc_calibration
值得注意的是,value 字段注释中"<0 maps to NaN"这一行为在消费端由混控器侧的 FunctionMotors::updateValues() 实现(见下文调用链),普通单向电机会将负值钳制为 NaN 从而停机,避免负油门风险。
生产端与消费端:完整调用链
生产端 1:actuator_test 命令行模块
PX4 提供了专门的系统命令 actuator_test 来发布该消息,模块入口为 src/systemcmds/actuator_test/actuator_test.cpp,其构建配置见 src/systemcmds/actuator_test/CMakeLists.txt。核心发布函数(第 53-64 行)构造 actuator_test_s 结构体并填充 timestamp、function、value、action、timeout_ms,然后通过 uORB::Publication<actuator_test_s> actuator_test_pub{ORB_ID(actuator_test)} 发布。
命令用法(在 PX4 终端 / NSH shell 中执行):
# 将第 1 个电机(功能编号 101)设置为 20% 输出,超时 5 秒
actuator_test set -m 1 -v 0.2 -t 5
# 将第 2 个舵机(功能编号 202)偏转到 +0.5,不设超时(交互模式,按 Enter 停止)
actuator_test set -s 2 -v 0.5
# 直接指定功能编号,例如 430(Gripper 夹爪)
actuator_test set -f 430 -v 1
# 依次启动/停止全部电机(每次 15% 输出、400ms 超时、间隔 600ms)
actuator_test iterate-motors
# 依次偏转全部舵机(每次 30% 输出、800ms 超时、间隔 1s)
actuator_test iterate-servos
各参数说明(与 actuator_test.cpp 的 usage 输出一致):
| 选项 | 含义 | 说明 |
|---|---|---|
-m <1..8> |
指定电机序号 | 实际功能编号 = FUNCTION_MOTOR1 + 序号 - 1(即 101 + n - 1) |
-s <1..8> |
指定舵机序号 | 实际功能编号 = FUNCTION_SERVO1 + 序号 - 1(即 201 + n - 1) |
-f <值> |
直接指定功能编号 | 对应 output_functions.yaml 中的编号 |
-v <值> |
输出值 | 范围 [-1, 1],越界报错 |
-t <秒> |
超时秒数 | 内部转换为毫秒存入 timeout_ms;不指定则进入交互模式 |
两个迭代子命令的实现细节(actuator_test.cpp)也值得注意:iterate-motors 循环发布 FUNCTION_MOTOR1+i(i 从 0 到 MAX_NUM_MOTORS-1,即最多 12 路),每路 15% 输出、400ms 超时、600ms 间隔;iterate-servos 循环发布 FUNCTION_SERVO1+i(最多 15 路),每路 30% 输出、800ms 超时、1 秒间隔。这两个命令非常适合装机后的快速通道巡检。
命令说明中还有一条醒目的安全警告:WARNING: remove all props before using this command.(使用前务必卸下所有螺旋桨)。
生产端 2:esc_calibration 电调校准模块
电调校准流程是 actuator_test 的另一个重要生产端。在 src/modules/commander/esc_calibration.cpp 中:
- 校准开始前调用
set_motor_actuators(actuator_test_pub, 1.f, false),向全部MAX_NUM_MOTORS路电机发布value = 1.0、ACTION_DO_CONTROL,让电调进入最大油门校准状态(第 108 行); - 随后发布
value = 0.f的ACTION_DO_CONTROL消息让电机进入最小油门状态(第 147 行); - 校准结束后发布
set_motor_actuators(actuator_test_pub, 0.f, true),以value = 0、ACTION_RELEASE_CONTROL释放所有通道(第 156 行)。
这正是 ORB_QUEUE_LENGTH 必须大于等于 MAX_NUM_MOTORS 的直接原因——该函数会在循环中连续 publish 12 条消息。
消费端:混控器模块的 ActuatorTest 类
真正的消费端位于 src/lib/mixer_module/actuator_test.cpp,其类声明在 src/lib/mixer_module/actuator_test.hpp。消费逻辑的核心流程如下:
- 订阅:类内部持有
uORB::Subscription _actuator_test_sub{ORB_ID(actuator_test)},并同步订阅actuator_motors(用于可逆电机标志)与actuator_servos_trim(用于舵机微调)两个话题; - 时效过滤:
update()中要求消息的timestamp非 0 且距当前时间不超过 100ms,防止陈旧消息误触发测试模式; - 匹配通道:遍历当前输出通道,找到
_function_assignments[i] == actuator_test.function的通道; - 进入测试模式:若收到
ACTION_DO_CONTROL,先reset()再置位_in_test_mode,并将该通道标记为_output_overridden; - 值处理:
- 对电机(function 落在
Motor1..MotorMax区间):读取actuator_motors的reversible_flags,经FunctionMotors::updateValues()处理(负值映射 NaN 等钳制逻辑在此完成),并应用推力曲线thrust_curve; - 对舵机(function 落在
Servo1..ServoMax区间):读取actuator_servos_trim,在value上叠加对应通道的 trim 值;
- 对电机(function 落在
- 输出覆盖:
overrideValues()在测试模式下用_current_outputs<a href="https://link.gitcode.com/i/204ab0252cedbfa60c3df36c4b3c58d3" target="_blank">]直接覆盖混控器计算结果;inTestMode()返回测试状态,混控器据此绕过输出限制(见 [mixer_module.cpp 中output_limit_calc(_throttle_armed || _actuator_test.inTestMode(), ...)); - 超时与释放:若
ACTION_RELEASE_CONTROL使所有通道均不再被覆盖,或到达_next_timeout超时时刻,自动退出测试模式。
日志记录
actuator_test 话题同样进入飞行日志。在 src/modules/logger/logged_topics.cpp 中可见 add_topic("actuator_test", 500);,即以 500Hz 的采样率写入日志,便于事后回放分析测试期间的指令与响应。
自定义模块中发布 / 订阅 actuator_test 的要点
结合上文调用链,在自定义模块中使用该消息时需注意以下几点(均由仓库源码佐证):
- 发布侧:务必设置
timestamp = hrt_absolute_time();消息体填充function(可用actuator_test_s::FUNCTION_MOTOR1 + idx或FUNCTION_SERVO1 + idx推算,或直接使用output_functions.yaml中的编号);value严格限制在 [-1, 1];需要自动退出时设置timeout_ms,否则用ACTION_RELEASE_CONTROL显式释放; - 订阅侧:混控器的
ActuatorTest::update()会丢弃超过 100ms 的陈旧消息,因此发布与执行之间延迟不应过大; - 队列长度:若你的模块需要像
esc_calibration一样突发连续发布多条消息,请确认订阅端队列长度足够(消息自带ORB_QUEUE_LENGTH = 16); - 安全:测试模式会绕过正常混控与部分输出限制,发布前务必确认执行机构环境安全(卸桨、固定机架)。
小结
actuator_test 是 PX4 中功能聚焦但链路完整的典型 uORB 消息:它以 5 个字段(timestamp / action / function / value / timeout_ms)承载单通道执行机构测试指令,以 7 个常量(动作类型、电机/舵机功能编号区间、队列长度)定义协议契约,生产端覆盖 actuator_test 命令行与 esc_calibration 电调校准,消费端则由混控器模块的 ActuatorTest 类完成通道匹配、值变换(推力曲线 / 舵机 trim / 可逆电机钳制)、超时退出与输出覆盖。理解这条消息的定义与实现,是进行执行机构调试、电调校准和混控器二次开发的基础。