# uORB 消息

## 简介

The uORB is an asynchronous publish() / subscribe() messaging API used for inter-thread/inter-process communication.

uORB 会在启动时自动启动，因为许多应用程序都依赖于它。 它以 uorb start</0 > 开头。 单元测试可以从 <code>uorb_tests 开始。

## 添加新 Topic（主题）

New uORB topics can be added either within the main PX4/Firmware repository, or can be added in an out-of-tree message definitions. For information on adding out-of-tree uORB message definitions, please see this section.

To add a new topic, you need to create a new .msg file in the msg/ directory and add the file name to the msg/CMakeLists.txt list. From this, the needed C/C++ code is automatically generated.

#include <uORB/topics/topic_name.h>


By adding a line like the following in the .msg file, a single message definition can be used for multiple independent topics:

# TOPICS mission offboard_mission onboard_mission


## 发布

Publishing a topic can be done from anywhere in the system, including interrupt context (functions called by the hrt_call API). However, advertising a topic is only possible outside of interrupt context. A topic has to be advertised in the same process as it's later published.

## 主题列表和监听（Listener）

listener 命令仅适用于 Pixracer (FMUv4) 和 Linux/OS X。

ls /obj


listener sensor_accel 5


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


### uorb top 命令

uorb top 命令实时显示每个主题的发布频率。

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


The columns are: topic name, multi-instance index, number of subscribers, publishing frequency in Hz, number of lost messages per second (for all subscribers combined), and queue size.

## 多实例

uORB provides a mechanism to publish multiple independent instances of the same topic through orb_advertise_multi. It will return an instance index to the publisher. A subscriber will then have to choose to which instance to subscribe to using orb_subscribe_multi (orb_subscribe subscribes to the first instance). Having multiple instances is useful for example if the system has several sensors of the same type.

## Message/Field Deprecation

As there are external tools using uORB messages from log files, such as Flight Review, certain aspects need to be considered when updating existing messages:

• Changing existing fields or messages that external tools rely on is generally acceptable if there are good reasons for the update. In particular for breaking changes to Flight Review, Flight Review must be updated before code is merged to master.
• In order for external tools to reliably distinguish between two message versions, the following steps must be followed:
• Removed or renamed messages must be added to the deprecated_msgs list in msg/CMakeLists.txt and the .msg file needs to be deleted.
• Removed or renamed fields must be commented and marked as deprecated. For example uint8 quat_reset_counter would become # DEPRECATED: uint8 quat_reset_counter. This is to ensure that removed fields (or messages) are not re-added in future.
• In case of a semantic change (e.g. the unit changes from degrees to radians), the field must be renamed as well and the previous one marked as deprecated as above.