Skip to content

Uorb improved docs - structure and comment format #24966

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
+224 −14
Draft

Uorb improved docs - structure and comment format #24966

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bad8602
Methodical uorb documentation
hamishwillee Jun 4, 2025
d4d3f8e
Improve intro, I hope
hamishwillee Jun 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 224 additions & 14 deletions docs/en/middleware/uorb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,35 @@
# uORB Messaging

The Micro Object Request Broker (uORB) is PX4s low-latency asynchronous `publish()` / `subscribe()` messaging API for inter-thread/inter-process communication.
It allows the different modules of the system to communicate effectively, while still being loosely coupled, and hence easily replaced.

## Introduction

The uORB is an asynchronous `publish()` / `subscribe()` messaging API used for inter-thread/inter-process communication.
PX4 modules communicate using uORB _topics_.
A topic represents a communication channel for sending _messages_ between a publisher module and one or more subscriber modules.
A module that is interested in receiving messages can subscribe to a topic and use it to check for, and read, new messages.
A module that wants to send messages to a particular topic (and hence all subscribers) must _advertise_ that it is going to do so, and can then _publish_ messages when it has new data.

A topic behaves like a queue to which publishers write, and from which subscribers read.
By default he queue can only buffer a single message, which may be overwritten if the publisher writes new message data before subscribers can read it.
The [queue size may be increased](#uorb-buffer-length-orb-queue-length) in the rare cases when subscribers really need to receive every message.

A message is a discrete sample of data that can be published/subscribed via a topic.
The message fields, the constants that can be used with those fields, and the topic(s) to which the message can be published/subscribed are defined in a uORB message definition file.

By default a single topic is automatically created for each message definition file, which is created by `underscore_snake_casing` the (CamelCase) message definition file name.
For example, topic `battery_status` is automatically created for the `BatteryStatus.msg`.
This is generally what you want if the message is always about the same kind of data (batteries in this case) and so all the subscribers will be interested in the same messages.

Sometimes the same message structure can be used to represent data from different kinds of sources, which will have different sets of interested publishers and subscribers.
In this case the topics need to be explicitly declared.
For example the [VehicleGlobalPosition.msg](../msg_docs/VehicleGlobalPosition.md) can be used for sending messages about global position from an estimator, GNSS, or an external source: the fields are the same, but the source and subscribers of the data may be different.

uORB also provides a mechanism to publish multiple independent instances of the same topic.
This is useful, for example, if the system has several sensors of the same type.

uORB is implemented in the [`uorb` module](../modules/modules_communication.md#uorb).
It is started automatically (with `uorb start`) early in the PX4 boot sequence, as many applications depend on it.
The module is started automatically (with `uorb start`) early in the PX4 boot sequence, as many applications depend on it.
Unit tests can be started with `uorb_tests`.

This document explains how to add uORB message definitions and their corresponding topic(s), how to use reference a topic in code, and how to view topics as they change in PX4.
Expand Down Expand Up @@ -42,20 +66,20 @@ In code you refer to the topic using its id, which in this example would be: `OR

## Message Definitions

The message definition should start with a descriptive _comment_ that outlines its purpose (a comment starts with the `#` symbol and goes to the end of the line).
Every message should start with a [message description](#message-description) that outlines its purpose (a comment starts with the `#` symbol and goes to the end of the line).
The message will then define one or more fields, which are defined with a _type_, such as `bool`, `uint8`, and `float32`, followed by a _name_.
By convention, each field is followed by a descriptive _comment_, which is any text from the `#` symbol to the end of the line.

::: warning
All message definitions **must** include the `uint64_t timestamp` field, and this should be filled in when publishing the associated topic(s).
This field is needed in order for the logger to be able to record UORB topics.
:::

::: info
All _versioned_ messages definitions must include the `uint32 MESSAGE_VERSION` field.
For more information, refer to the [Message Versioning](#message-versioning) section.
:::

::: warning
All message definitions **must** include the `uint64_t timestamp` field, and this should be filled in when publishing the associated topic(s).
This field is needed in order for the logger to be able to record UORB topics.
:::

For example the [VelocityLimits](../msg_docs/VelocityLimits.md) message definition shown below has a descriptive comment, followed by a number of fields, which each have a comment.

```text
Expand All @@ -74,16 +98,202 @@ By default this message definition will be compiled to a single topic with an id
This is the simplest form of a message.
See the existing [`msg`](../msg_docs/index.md) files for other examples of how messages are defined.

### Multi-Topic Messages
#### Message Description

Every message should start with a [comment](#comments) block that describes the message (one or more of lines that all start with `#`).
The first comment line is mandatory and provides the short description.
This may be followed by an empty comment line and then a optional long description.

```text
# Short description
#
# Long(er) description for the message
# that can be multiline
```

The short description should provide a succinct explanation for the purpose of the message.
Minimally it may just mirror the message name.
For example, [`BatteryStatus`](../msg_docs/BatteryStatus.md) has the short description `Battery status`.

The long description should provide any additional context required to understand what how the message is used.
It might explain who are the publishers and who are the expected consumers, such as MAVLink or the logging system.
It might also cover whether the message is only used for a particular frame type or mode.

Both short and long descriptions may be multi-line.
The long description may also include empty comment lines (the short description cannot, because the first empty comment delineates the short and long description).
A terminating full stop can be omitted from single line comments and from the final line.

The block ends at the first non-comment line, such as an empty line, field, or constant.
Any subsequent comment lines are considered "internal comments".

### Comments

Comments are text provided for explanation or documentation purposes.
Any text after a `#` character is a comment (with the exception of lines that [start with `# TOPIC`](#multi-topic-message)).

PX4 uses structured comments for message, field, and constant descriptions.
Other comments are internal.

### Fields

Messages define one or more fields, which are the variables that are written and read by publishers and subscribers, respectively.

A typical field might look like this:

```sh
float64 lat # [deg] Latitude (WGS84).
```

Each field has a _type_ followed by a _name_, and should also have a _comment_
The format is as shown:

```sh
<type> <name> # [metadata] <description>
```

- `type`:
- A primitive data type: `bool`, `char`, `uint8`, `uint32`, `uint64`, `int8`, `int16`, `int32`, `float32` and `float64`.
- Another UORB message name, when creating complex types using [nested messages](#nested-messages).
- `name`
- Any message-unique string.
By convention use lower case `underline_snake_case`.

The comment must all be on the same line as the field, and should consist of optional metadata and a description:

- `metadata` (Optional)
- Information about the field units and allowed values:
- `[<unit>]`
- The unit of measurement inside square brackets (note, no `@` delineator indicates a unit).
For example `[m]` or `[deg]`.
Typical units include: `m`, `deg`, `m/s`, `rad`, `rad/s`, and so on.
- `[@enum <enum_name>]`
- The `enum_name` gives the prefix of constant values in the message that can be assigned to the field.
Note that in UORB "enums" are a naming convention: they are not explicitly declared.
Multiple enum names indicate a possible error in the field design.
- `[@range <lower_value>, <upper_value>]`
- The allowed range of the field, specified as a `lower_value` and/or an `upper_value`.
Either value can be omitted to indicate an unbounded upper or lower value.
For example `[@range 0, 3]`, `[@range 5.3, ]`, `[@range , 3]`.
- `[@invalid <value> <description>]`
- The `value` to set the field to indicate that the field doesn't contain valid data.
The `description` is optional, and might be used to indicate the conditions under which data is invalid.
- `description`
- A concise description of the purpose of the field and allowed values, and including any important information that can't be inferred from the name!
Use a capital first letter, and omit the full stop if the description is a single sentence.
Multiple sentences may also omit the final full stop.

#### Array Fields

A array field defines multiple variables in an array, where all values have the same type.
The number of elements are given using square brackets after the type.
Array fields are otherwise defined (and documented) in the same way as other fields.

For example:

```sh
int32[12] raw_data # ADC channel raw value, accept negative value.
```

#### Mandatory Fields

All message definitions **must** include following fields:

- `uint64_t timestamp`
- This should be filled in when publishing the associated topic(s).
It is needed in order for the logger to be able to record UORB topics.
- The comment should be `# [us] Time since system start`.

### Constants

Constants specify a mapping between a name and a value.

These are mainly used to predefine useful values that you might need to use for a particular field, such as a state or flag values.
Often these are grouped together as [enums](#enums).
There are also a small number of [metadata constants](#metadata-constants) that are used by the build infrastructure.

For example, here are a number of constants for indicating battery warnings.

```sh
uint8 WARNING_NONE = 0 # No battery low voltage warning active
uint8 WARNING_LOW = 1 # Low voltage warning
```

Constants are specified as a field assigned with a value.
The field part has a _type_, which must match the type of the field they are to be used with, followed by a _name_.
They should also have a _comment_ with a description.
By convention they are defined immediately below the field with which they can used.

The format is as shown:

```sh
<type> <name> = <value> # <description>
```

- `type`:
- Must match the `type` of the field with which it is to be used.
- `name`
- The name of the constant.
This must be message-unique and is by convention `ALL_UPPER_CASE_UNDERLINE_SNAKE_CASE`
- Constant names that can be used with a field should share the same prefix and should indicate the value's purpose.

The comment must all be on the same line as the field.
Note that this is much like the field description (but there is no metadata):

- `description`
- A terse description of the purpose of the constant.
Use a capital first letter, and omit the full stop if the description is a single sentence.
Multiple sentences may also omit the final full stop.

#### Enums

Enums are groups/sets of enumerated constants that can be used as values for a particular field.

UORB does not define a formal syntax for enums.
Instead we use a prefix naming convention to indicate all the constants that are part of the same enum.
The constants in the enum should be declared immediately after the field in which they are used, and for parsing convenience, the prefix is listed in the field using `@enum` metadata.

For example, here is the definition of the `warning` field and some of the `WARNING` enum values that can be used with it:

```sh
uint8 warning # [@enum WARNING] Current battery warning
uint8 WARNING_NONE = 0 # No battery low voltage warning active
uint8 WARNING_LOW = 1 # Low voltage warning
uint8 WARNING_CRITICAL = 2 # Critical voltage, return / abort immediately
...
```

#### Metadata Constants

A number of constants provide information that is used by the PX4 build system to configure how the message may be used, such as the version and length of the message.
If relevant, these should appear near the top of the file, immediately after the [Message Description](#message-description).

The allowed constants are:

- `ORB_QUEUE_LENGTH` - Sets the [uORB Buffer Length](#uorb-buffer-length-orb-queue-length), which is used in rare cases where a subscriber needs all values that are set for a field, rather than just the most recent sample.
- `MESSAGE_VERSION` - Sets the version number of a versioned message.
This is used as part of the infrastructure to maintain compatibility between PX4 and ROS 2 versions compiled against different message definitions.
For more information see [Message Versioning](#message-versioning)

#### Multi-Topic Messages (`# TOPICS`) {#multi-topic-messages}

By default a single topic is automatically created for each message definition file, which is created by `underscore_snake_casing` the (CamelCase) message definition file name.
For example, topic `battery_status` is automatically created for the `BatteryStatus.msg`.
This is generally what you want if the message is always about the same kind of data (batteries in this case) and so all the subscribers will be interested in the same messages.

Sometimes it is useful to use the same message definition for multiple topics.
This can be specified at the end of the message using a line prefixed with `# TOPICS `, followed by space-separated topic ids.
For example, the [ActuatorOutputs](../msg_docs/ActuatorOutputs.md) message definition is used to define the topic ids as shown:
In this case the topics need to be explicitly declared.
You can do this by adding one or more lines to the end of the message prefixed with `# TOPICS`, followed by space-separated topic ids.

For example, the [VehicleGlobalPosition.msg](../msg_docs/VehicleGlobalPosition.md) message definition is used to define the topic ids as shown:

```text
# TOPICS actuator_outputs actuator_outputs_sim actuator_outputs_debug
# TOPICS vehicle_global_position vehicle_global_position_groundtruth external_ins_global_position
# TOPICS estimator_global_position
# TOPICS aux_global_position
```

Note that multiple topics are useful in this case because the likely subscribers for the different sources of global position are likely to be different.

### Nested Messages

Message definitions can be nested within other messages to create complex data structures.
Expand All @@ -95,7 +305,7 @@ To nest a message, simply include the nested message type in the parent message
#
# This are the three next waypoints (or just the next two or one).

uint64 timestamp # [us] Time since system start.
uint64 timestamp # [us] Time since system start

PositionSetpoint previous
PositionSetpoint current
Expand Down Expand Up @@ -133,7 +343,7 @@ As there are external tools using uORB messages from log files, such as [Flight
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.

## Message Versioning
## Message Versioning (MESSAGE_VERSION) {#message-versioning}

<Badge type="tip" text="PX4 v1.16" />

Expand Down