嵌入式物联网机器人自动驾驶智能硬件【免费下载链接】PX4-AutopilotPX4 Autopilot Software项目地址https://gitcode.com/gh_mirrors/px/PX4-Autopilot点击查看免费下载uORBMicro Object Request Broker是 PX4 Autopilot 内部用于线程间/进程间通信的异步publish()/subscribe()消息中间件几乎所有飞控模块传感器驱动、状态估计、控制器、导航都依赖它交换数据。本文以官方 uORB 文档为主体结合仓库内真实消息定义与源码实现完整讲解如何新增 uORB 话题、如何用 C 发布与订阅、如何用listener/uorb top在线调试以及 PX4 v1.16 引入的消息版本化机制读完即可在 msg/ 目录下从零定义一个可被全系统使用的话题。1. uORB 是什么PX4 内部的发布/订阅消息总线uORB 是一套异步的publish()/subscribe()消息 API用于 PX4 内部各线程与各进程之间的通信。其核心特征在于“异步且无锁”发布者不会等待订阅者订阅者也不会阻塞发布者两者之间通过独立的缓冲区完成数据交换从而在保证极低时延的同时尽量压缩内存占用见 src/systemcmds/uorb/uorb.cpp 中的模块描述。uORB 在 PX4 启动序列的早期阶段就由uorb start自动拉起因为大量应用模块在初始化时就要依赖它完成话题发布与订阅单元测试则可以通过uorb_tests命令启动。它的完整实现位于 platforms/common/uORB/其中uORB.h 定义了对外暴露的 C APIorb_advertise、orb_publish、orb_subscribe、orb_copy等uORBManager.hpp 是核心管理器负责话题节点的创建、发布与订阅分发uORBDeviceNode.hpp 与 uORBDeviceMaster.cpp 实现话题节点及其元数据管理test/ 与 uORB_tests/ 包含大量单元测试例如 uORBTest_UnitTest.cpp 验证了队列长度、消息序号回绕wrap-around等边界行为。进阶阅读uORB 的现代 C 封装uORB::Publication、uORB::Subscription、uORB::SubscriptionCallback等位于 Publication.hpp、Subscription.hpp、SubscriptionCallback.hpp它们提供了比裸 C API 更安全、更易用的 RAII 风格接口First Application Tutorial (Hello Sky) 对此有完整示例。2. 新增一个 uORB 话题新增 uORB 话题可以在 PX4 主仓库内完成也可以通过 out-of-tree 消息定义 在仓库之外定义。主仓库内的添加流程分三步编写 .msg 文件 → 在 CMakeLists.txt 中登记 → 构建时自动生成 C/C 代码。2.1 创建 .msg 消息定义文件新建一个遵循CamelCase命名约定的.msg消息定义文件放置于 msg/ 目录若该消息需要版本化即需要暴露给 ROS 2 并保持跨版本兼容则放到 msg/versioned 子目录。随后将该文件名登记到 msg/CMakeLists.txt 的msg_files列表中例如文件列表中真实存在的VelocityLimits.msg、versioned/VehicleAttitude.msg等条目。一个消息定义文件可以定义一个或多个topics话题它们共享相同的字段与结构。默认情况下一个定义文件只生成一个话题话题名是文件名 CamelCase 到 snake_case 的转换结果——例如TopicName.msg会定义话题topic_name。2.2 自动生成代码与使用方式从消息定义出发构建系统会自动生成所需的 C/C 代码。生成逻辑位于 msg/CMakeLists.txt由 Tools/msg/px_generate_uorb_topic_files.py 配合 Tools/msg/templates/uorb 下的.em模板生成话题头文件输出到构建目录uORB/topics/、话题源文件以及uORBTopics.hpp同时会生成 microCDR 序列化头文件供 ROS 2 / Zenoh 桥使用与消息 JSON 元数据。在代码中使用话题时先包含以 snake_case 命名的生成头文件。例如消息名为VelocityLimits则头文件为velocity_limits.h#include uORB/topics/velocity_limits.h代码中通过话题 id 引用它即ORB_ID(velocity_limits)。所有话题的 ORB_ID 枚举统一生成在uORBTopics.hpp中该枚举由 uORBManager.hpp 引用。3. 消息定义格式详解消息定义文件以#开头的描述性注释说明用途注释从#到行尾结束随后定义一个或多个字段每个字段由类型如bool、uint8、float32加名称构成按惯例每个字段后紧跟一行描述性注释。3.1 必须遵守的两条铁律所有消息定义必须包含uint64_t timestamp字段并且在发布话题时填充其值。该字段是日志系统logger记录 uORB 话题的前提缺少它将无法写入飞行日志。所有版本化消息定义必须包含uint32 MESSAGE_VERSION字段详见第 6 节。3.2 最简消息示例VelocityLimits仓库中真实的 VelocityLimits.msg 如下它定义了多旋翼位置慢速模式下的速度与偏航角速度限制# Velocity and yaw rate limits for a multicopter position slow mode only uint64 timestamp # time since system start (microseconds) # absolute speeds, NAN means use default limit float32 horizontal_velocity # [m/s] float32 vertical_velocity # [m/s] float32 yaw_rate # [rad/s]uint64 timestamp单位为微秒µs表示系统启动以来的时间float32 horizontal_velocity单位为 m/s为绝对水平速度限制NAN表示使用默认限制float32 vertical_velocity单位为 m/s垂直速度限制float32 yaw_rate单位为 rad/s偏航角速度限制。默认情况下该定义编译为单一话题velocity_limitsCamelCase 到 snake_case 的直接转换。更多真实消息示例可参考 docs/en/msg_docs/index.md 下的全部消息文档。3.3 多话题消息Multi-Topic Messages有时需要让同一个消息定义服务于多个话题。可在消息文件末尾使用# TOPICS前缀行后跟空格分隔的话题 id 列表。例如 ActuatorOutputs.msg 末尾的真实定义# actuator_outputs_sim is used for SITL, HITL SIH (with an output range of [-1, 1]) # TOPICS actuator_outputs actuator_outputs_sim actuator_outputs_debug这会让同一个输出结构同时生成actuator_outputs真实输出、actuator_outputs_sim仿真输出与actuator_outputs_debug调试输出三个话题。注意这与第 5 节的“多实例”机制不同多话题是“结构相同但话题不同”多实例是“话题相同但实例不同”。3.4 嵌套消息Nested Messages消息定义可以嵌套其他消息以构造复杂数据结构——只需在父消息定义中直接引用子消息类型即可。例如 PositionSetpointTriplet.msg 就嵌套了三个PositionSetpoint# Global position setpoint triplet in WGS84 coordinates. # This are the three next waypoints (or just the next two or one). uint64 timestamp # time since system start (microseconds) PositionSetpoint previous PositionSetpoint current PositionSetpoint next其中PositionSetpoint自身的字段定义见 PositionSetpoint.msg另可参考其文档 docs/en/msg_docs/PositionSetpoint.md。嵌套消息在生成代码时会被展开为结构体成员且遵循同样的对齐规则。3.5 队列长度常量ORB_QUEUE_LENGTHuORB 消息默认只有一个单消息缓冲如果发布频率过高旧消息可能被覆盖。大多数情况下这无关紧要——我们通常只关心传感器值或设定点这类话题的“最新一帧”丢几帧也无妨但对vehicle_command这类指令型话题丢消息是不能接受的。为降低丢消息概率可用命名常量ORB_QUEUE_LENGTH创建指定长度的缓冲队列。例如在消息定义中加入uint8 ORB_QUEUE_LENGTH 4即可创建一个 4 消息队列。只要订阅者读取速度足够快、缓冲从未被发布者写满订阅者就能收到全部消息若队列已满时仍有新消息发布消息仍会丢失。注意队列长度必须是 2 的幂如 2、4、8……。从源码看队列长度通过ORB_DEFINE宏写入话题元数据orb_metadata见 uORB.h运行时可通过orb_get_queue_size()uORB.cpp查询订阅者可通过 uORBManager.hpp 中的ORBIOCDEVQUEUESIZEioctl 读取队列大小。单元测试 uORBTest_UnitTest.cpp 中大量使用orb_get_queue_size与消息序号回绕场景验证了队列机制的健壮性。3.6 字段/消息废弃Deprecation由于存在 Flight Review 等基于日志文件解析 uORB 消息的外部工具更新既有消息时必须格外谨慎出于合理原因修改外部工具依赖的既有字段/消息通常可接受若构成对 Flight Review 的破坏性变更必须在代码合入master之前先更新 Flight Review。为了让外部工具可靠地区分两个消息版本必须遵循以下步骤删除或重命名的消息加入 msg/CMakeLists.txt 的deprecated_msgs列表并删除对应的.msg文件删除或重命名的字段注释掉并标记为废弃例如uint8 quat_reset_counter应改为# DEPRECATED: uint8 quat_reset_counter以确保被移除的字段/消息不会在未来被重新添加语义变更如单位从度改为弧度字段必须同时改名并将旧字段按上述方式标记为废弃。4. 在代码中发布话题发布话题可以在系统任意位置进行包括中断上下文即由hrt_callAPI 调用的函数。但话题必须先在非中断上下文中完成 advertise发布通告并至少发布一次之后才能在中断上下文中发布。核心 C API 定义在 uORB.hAPI作用orb_advertise(meta, data)通告并发布话题创建话题节点并发布初始数据orb_advertise_multi(meta, data, instance)创建指定话题的新实例并返回实例索引orb_publish(meta, handle, data)发布新数据orb_publish_auto(meta, handle, data, instance)自动完成首次通告与后续发布orb_subscribe(meta)/orb_subscribe_multi(meta, instance)订阅话题默认订阅第一个实例orb_copy(meta, handle, buffer)拷贝最新数据orb_check(handle, updated)检查是否有新数据orb_unadvertise(handle)/orb_unsubscribe(handle)撤销通告 / 退订注意广告句柄orb_advert_t是全局的一旦获得可以自由共享无需关闭或释放——这也正是它允许在中断上下文等无法使用文件描述符的场景下继续发布的原因见 uORB.h 的注释。4.1 多实例Multi-instanceuORB 支持为同一个话题发布多个相互独立的实例例如系统装有多个同型号传感器时非常有用。发布方调用orb_advertise_multi创建新实例并获得其实例索引订阅方需要用orb_subscribe_multi选择要订阅的实例而orb_subscribe默认订阅第一个实例。务必注意同一个话题不要混用orb_advertise_multi与orb_advertise完整的 API 文档见 platforms/common/uORB/uORBManager.hpp。实例的数量可由orb_group_count()查询uORB.h。5. 在线查看与调试话题5.1 列出所有话题ls /obj在 PX4 终端NuttX shell 或 MAVLink Shell中uORB 话题以文件句柄形式挂在/obj虚拟文件系统下列出即可查看当前存在的所有话题ls /obj5.2 监听单个话题listener命令listener命令在大多数 FMUv4 之后的板上可用是否编译由板级 Kconfig 中的CONFIG_SYSTEMCMDS_TOPIC_LISTENER决定实现见 src/systemcmds/topic_listener/。监听一个话题最近的 5 条消息listener sensor_accel 5输出为话题内容的 n 次打印真实输出形如TOPIC: sensor_accel #3 timestamp: 84978861 integral_dt: 4044 error_count: 0 x: -1 y: 2 z: 100 x_integral: -0 y_integral: 0 z_integral: 0 temperature: 46 range_m_s2: 78 scaling: 0 TOPIC: sensor_accel #4 timestamp: 85010833 integral_dt: 3980 error_count: 0 x: -1 y: 2 z: 100 x_integral: -0 y_integral: 0 z_integral: 0 temperature: 46 range_m_s2: 78 scaling: 0从 listener_main.cpp 的实现看listener还支持更多参数-i instance指定订阅实例-r rate指定监听频率-n num指定监听消息条数listener topic num的第二个位置参数正是-n的快捷形式。调试技巧在 NuttX 系统Pixhawk、Pixracer 等上listener可以直接从 QGroundControl 的MAVLink Console中调用用于查看传感器及其他话题的值。即使在无线链路如飞行中场景下也能工作是一个强大的调试工具。更多用法见 Sensor/Topic Debugging。5.3 实时发布频率统计uorb topuorb top命令实时显示每个话题的发布频率由 src/systemcmds/uorb/uorb.cpp 实现uorb status打印话题统计uorb top监视发布速率支持-a显示所有话题、-1只运行一次、以及可选的 topic 过滤参数。典型输出update: 1s, num topics: 77 TOPIC NAME INST #SUB #MSG #LOST #QSIZE actuator_armed 0 6 4 0 1 actuator_controls_0 0 7 242 1044 1 battery_status 0 6 500 2694 1 commander_state 0 1 98 89 1 control_state 0 4 242 433 1 ekf2_innovations 0 1 242 223 1 ekf2_timestamps 0 1 242 23 1 estimator_status 0 3 242 488 1 mc_att_ctrl_status 0 0 242 0 1 sensor_accel 0 1 242 0 1 sensor_accel 1 1 249 43 1 sensor_baro 0 1 42 0 1 sensor_combined 0 6 242 636 1各列含义为话题名、多实例索引INST、订阅者数量#SUB、发布频率Hz即 #MSG、每秒丢失消息数#LOST所有订阅者合计、队列大小#QSIZE。#LOST非零往往意味着订阅者处理速度跟不上发布速率是排查话题拥塞的直接线索——例如上例中actuator_controls_0每秒丢失 1044 条消息。5.4 话题变化实时绘图话题变化可以用 PlotJuggler 结合 PX4 ROS 2 集成实时绘图实际绘制的是与 uORB 话题对应的 ROS 话题效果一致。详见 Plotting uORB Topic Data in Real Time using PlotJuggler。6. 消息版本化Message Versioning功能标签PX4 v1.16 引入。消息版本化可选于 PX4 v1.16 引入目的是让编译自不同消息定义的 PX4 与 ROS 2 之间更容易保持兼容。版本化消息比非版本化消息设计得更稳定——它们要跨多个 PX4 版本和外部系统使用因此长期兼容性更好。版本化消息额外包含一个字段uint32 MESSAGE_VERSION x其中x对应消息的当前版本号。仓库中真实的版本化消息示例可见 msg/versioned/VehicleAttitude.msguint32 MESSAGE_VERSION 0同时用# TOPICS声明了vehicle_attitude、vehicle_attitude_groundtruth、external_ins_attitude、estimator_attitude等多个话题以及 msg/versioned/BatteryStatus.msg 等。版本化与非版本化消息在文件系统中是分开存放的非版本化的话题消息文件与 server service 消息文件分别位于 msg/ 与 srv/ 目录消息的当前最高版本文件位于versioned子目录msg/versioned 与 srv/versioned注意srv/versioned实际挂载于 msg/versioned 同级结构之下消息的旧版本存放在嵌套的 msg/px4_msgs_old/ 子目录中如 msg/px4_msgs_old/msg/ 与 msg/px4_msgs_old/srv/文件以版本号后缀重命名例如BatteryStatusV0.msg、ActuatorServosV0.msg、AirspeedValidatedV0.msg等。文件结构细节可进一步参考 File structure (ROS 2 Message Translation Node)。ROS 2 Message Translation Node 正是利用上述消息定义将编译自不同消息版本的 PX4 与 ROS 2 应用之间发送的消息无缝转换。更新版本化消息比更新非版本化消息涉及更多步骤详见 Updating a Versioned Message。全部版本化/非版本化消息的完整列表见 uORB Message Reference关于 PX4 与 ROS 2 通信的整体方案可参考 PX4-ROS 2 Bridge。说明ROS 2 计划在未来原生支持消息版本化但当前尚未实现参见 ROS Enhancement Proposal REP 2011 及相关讨论。7. 消息文档规范编写消息定义时建议遵循 uORB Documentation Standard 的规范以便自动生成高质量的 msg_docs 文档消息以注释块开头第一行为必填的简短描述可跟空注释行和更长的说明字段注释写在字段同一行、以空格分隔先写元数据如单位[m/s]、[rad/s]再可写允许值[enum ...]、非法值[invalid NaN]与取值范围[range min, max]除布尔字段或枚举字段外单位是必需的无量纲字段用[-]表示常量如枚举值SOURCE_DISABLED -1不带元数据注释跟在注释符后一个空格相同前缀的常量聚在一起形成枚举。典型示例以 AirspeedValidated.msg 为蓝本# Validated airspeed # # Provides information about airspeed (indicated, true, calibrated) and the source of the data. uint32 MESSAGE_VERSION 1 uint64 timestamp # [us] Time since system start float32 indicated_airspeed_m_s # [m/s] [invalid NaN] Indicated airspeed (IAS) float32 true_airspeed_m_s # [m/s] [invalid NaN] True airspeed (TAS) int8 airspeed_source # [enum SOURCE] Source of currently published airspeed values int8 SOURCE_DISABLED -1 # Disabled int8 SOURCE_SENSOR_1 1 # Sensor 1 int8 SOURCE_SYNTHETIC 4 # Synthetic airspeed8. 从 .msg 到可运行代码的完整链路回顾整个消息生命周期可以清晰地看到“定义 → 生成 → 使用 → 调试”的闭环定义在 msg/或 msg/versioned编写.msg文件登记进 msg/CMakeLists.txt生成构建时由 Tools/msg/px_generate_uorb_topic_files.py 生成话题头文件uORB/topics/*.h、话题源文件、uORBTopics.hpp枚举、JSON 元数据以及 microCDR 序列化头用于 ROS 2 桥使用在模块代码中#include uORB/topics/topic.h通过ORB_ID(topic)引用用orb_advertise/orb_publish发布、orb_subscribe/orb_copy订阅uORB 管理器 uORBManager.hpp 负责话题节点的实际创建与分发调试ls /obj列话题、listener topic [n]看内容、uorb top看频率与丢包结合日志系统记录 timestamp 字段完成飞行数据复盘。掌握这条链路你就可以在 PX4 中自定义任意模块间通信协议并借助uorb top的#LOST列持续监控话题健康度确保飞行系统的实时性要求得到满足。赞分享嵌入式物联网机器人自动驾驶智能硬件【免费下载链接】PX4-AutopilotPX4 Autopilot Software项目地址https://gitcode.com/gh_mirrors/px/PX4-Autopilot点击查看免费下载相关推荐AsyncAwaitBestPractices MVVM实战AsyncCommand和AsyncValueCommand的完整教程AsyncAwaitBestPractices MVVM实战AsyncCommand和AsyncValueCommand的完整教程 在.NET开发中异步编程开发工具软件架构PX4 DebugArray UORB 消息详解从字段定义到 Mavlink 调试链路实战PX4 DebugArray UORB 消息详解从字段定义到 Mavlink 调试链路实战 PX4 的 debug_array 是一类专用于批量浮点调试数据的嵌入式物联网机器人自动驾驶智能硬件PX4 DebugVect UORB 消息详解三维向量调试数据的定义、发布与链路PX4 DebugVect UORB 消息详解三维向量调试数据的定义、发布与链路 本篇技术指南以 PX4 Autopilot 仓库中 docs/en/msg_嵌入式物联网机器人自动驾驶智能硬件上一篇Superpowers 安装与上手教程3 步让 AI 编程代理学会专业开发流程下一篇swagger-codegen 生成的 Java Jersey2 客户端模型 Order 详解字段、状态枚举与 Store API 实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考