From b7ffd6ea2c2e14bfa9cf04532b29661629e4e129 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 18 Dec 2025 17:08:41 +1100 Subject: [PATCH] uORB doc standard - add page (#25878) --- docs/en/SUMMARY.md | 1 + docs/en/middleware/uorb.md | 2 + docs/en/uorb/uorb_documentation.md | 170 +++++++++++++++++++++++++++++ 3 files changed, 173 insertions(+) create mode 100644 docs/en/uorb/uorb_documentation.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 0d696d602e..80252fbdba 100644 --- a/docs/en/SUMMARY.md +++ b/docs/en/SUMMARY.md @@ -501,6 +501,7 @@ - [PPS Time Synchronization](advanced/pps_time_sync.md) - [Middleware](middleware/index.md) - [uORB Messaging](middleware/uorb.md) + - [uORB Docs Standard](uorb/uorb_documentation.md) - [uORB Graph](middleware/uorb_graph.md) - [uORB Message Reference](msg_docs/index.md) - [Versioned](msg_docs/versioned_messages.md) diff --git a/docs/en/middleware/uorb.md b/docs/en/middleware/uorb.md index ebd6a592df..401f3329b8 100644 --- a/docs/en/middleware/uorb.md +++ b/docs/en/middleware/uorb.md @@ -280,6 +280,8 @@ For more information see: [Plotting uORB Topic Data in Real Time using PlotJuggl ## See Also +- [uORB Documentation Standard](../uorb/uorb_documentation.md) + - _PX4 uORB Explained_ Blog series - [Part 1](https://px4.io/px4-uorb-explained-part-1/) - [Part 2](https://px4.io/px4-uorb-explained-part-2/) diff --git a/docs/en/uorb/uorb_documentation.md b/docs/en/uorb/uorb_documentation.md new file mode 100644 index 0000000000..a596014216 --- /dev/null +++ b/docs/en/uorb/uorb_documentation.md @@ -0,0 +1,170 @@ +# uORB Documentation Standard + +This topic demonstrates and explains how to document uORB messages. + +::: info +At time of writing many topics have not been updated. +::: + +## Overview + +The [AirspeedValidated](../msg_docs/AirspeedValidated.md) message shown below is a good example of a uORB topic that has been documented to the current standard. + +```py +# Validated airspeed +# +# Provides information about airspeed (indicated, true, calibrated) and the source of the data. +# Used by controllers, estimators and for airspeed reporting to operator. + +uint32 MESSAGE_VERSION = 1 + +uint64 timestamp # [us] Time since system start + +float32 indicated_airspeed_m_s # [m/s] [@invalid NaN] Indicated airspeed (IAS) +float32 calibrated_airspeed_m_s # [m/s] [@invalid NaN] Calibrated airspeed (CAS) +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_GROUND_MINUS_WIND = 0 # Ground speed minus wind +int8 SOURCE_SENSOR_1 = 1 # Sensor 1 +int8 SOURCE_SENSOR_2 = 2 # Sensor 2 +int8 SOURCE_SENSOR_3 = 3 # Sensor 3 +int8 SOURCE_SYNTHETIC = 4 # Synthetic airspeed + +float32 calibrated_ground_minus_wind_m_s # [m/s] [@invalid NaN] CAS calculated from groundspeed - windspeed, where windspeed is estimated based on a zero-sideslip assumption +float32 calibraded_airspeed_synth_m_s # [m/s] [@invalid NaN] Synthetic airspeed +float32 airspeed_derivative_filtered # [m/s^2] Filtered indicated airspeed derivative +float32 throttle_filtered # [-] Filtered fixed-wing throttle +float32 pitch_filtered # [rad] Filtered pitch +``` + +The main things to note are: + +- Documentation is added using formatted uORB comments. + Any text on a line after the `#` character is a comment, except for lines that start with the text `# TOPIC` (which indicates a multi-topic message). +- The message starts with a comment block consisting of short description (mandatory), followed by a longer description and then a space. +- Field and constants almost all have comments. + The comments are added on the same line as the field/constant, separated by one space. +- Fields: + - Comments are all on the same line as the field (extra lines become internal comments). + - Comments start with metadata, such as the units (`[m/s]`, `[rad/s]`) or allowed values (`[@enum SOURCE]`), and can also list invalid values (`[@invalid NaN]`) and allowed ranges (`[@range min, max]`). + - Units are required except for boolean fields or for fields with an enum value. + `[-]` is used to indicate unitless fields. + - Comments follow the metadata after a space. + The line should not be terminated in a full stop. +- Constants: + - Don't have metadata: the description follows the comment marker after one space. + - Some constants, such as `MESSAGE_VERSION`, don't need documentation because they are standardized. + - Constants with the same name prefix are grouped together as enums after the associated field. + +The following sections expand on the allowed formats. + +## Message Description + +Every message should start with a comment block that describes the message: + +```py +# Short description (mandatory) +# +# Longer description for the message if needed. +# Can be multiline, and should have punctuation. +# Should be followed by an empty line. +``` + +This consists of a mandatory short description, optionally followed by an empty comment line, and then a longer description. + +Short description (mandatory): + +- A succinct explanation for the purpose of the message. +- Usually just one line without a terminating full stop. +- Minimally it may just mirror the message name. +- For example, [`AirspeedValidated`](../msg_docs/AirspeedValidated.md) above has the short description `Validated airspeed`. + +Long description (Optional): + +- Additional context required to understand how the message is used. +- In particular this should be anything that can't be inferred from the name, fields or constants, such as the publishers and expected consumers. + It might also cover whether the message is only used for a particular frame type or mode. +- The message is often multiline and contains punctuation. +- May include comment lines that are empty, in order to indicate paragraphs. + +Both short and long descriptions may be multi-line. +Single line descriptions should not include a terminating full stop, but multiline comments should do so. + +The message description block ends at the first non-comment line, which should be an empty line, but might be a field or constant. +Any subsequent comment lines are considered "internal comments". + +### Fields + +A typical field comment looks like this: + +```py +float32 indicated_airspeed_m_s # [m/s] [@invalid NaN] Indicated airspeed (IAS) +``` + +Field comments must all be on the same line as the field, and consist of optional metadata followed by a description: + +- `metadata` (Optional) + - Information about the field units and allowed values: + - `[]` + - The unit of measurement inside square brackets (note, no `@` delineator indicates a unit), such as `[m]` for metres. + - Allowed units include: `m`, `m/s`, `m/s^2`, `rad`, `rad/s`, `rpm`, `V`, `A`, `mA`, `mAh`, `W`, `dBm`, `s`, `ms`, `us`, `Ohm`, `MB`, `Kb/s`, `degC`, `Pa`. + - Units are required unless clearly invalid, such as when the field is a boolean, or is an enum value. + - Unitless values should be specified as `[-]`. + Note though that units are not required for boolean fields or enum fields. + - `[@enum ]` + - The `enum_name` gives the prefix of constant values in the message that can be assigned to the field. + Note that enums in uORB are just a naming convention: they are not explicitly declared. + Multiple enum names allowed for a field indicates a possible error in the field design. + - `[@range , ]` + - 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 ]` + - The `value` to set the field to indicate that the field doesn't contain valid data, such as `[@invalid NaN]`. + The `description` is optional, and might be used to indicate the conditions under which data is invalid. + - `[@frame ]` + - The `frame` in which the field is set, such as `[@frame NED]` or `[@frame Body]`. +- `description` + - A concise description of the purpose of the field, 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. + +### Constants + +Constants follow the documentation conventions as fields except they only have a description (no metadata). +Documentation for a constant might look like this: + +```py +int8 SOURCE_GROUND_MINUS_WIND = 0 # Ground speed minus wind +``` + +Constants are often grouped together following a field as enum values. +Note below how the prefix `SOURCE` for the values is specified as an enum against the _field_. + +```py +int8 airspeed_source # [@enum SOURCE] Source of currently published airspeed values +int8 SOURCE_DISABLED = -1 # Disabled +int8 SOURCE_GROUND_MINUS_WIND = 0 # Ground speed minus wind +... +``` + +A small number of constants have a standardised meaning and do not require documentation. +These are: + +- `ORB_QUEUE_LENGTH` +- `MESSAGE_VERSION` + +### `# TOPICS` + +The prefix `# TOPICS` is used to indicate topic names for multi-topic messages. +For example, the [VehicleGlobalPosition.msg](../msg_docs/VehicleGlobalPosition.md) message definition is used to define the topic ids as shown: + +```text +# TOPICS vehicle_global_position vehicle_global_position_groundtruth external_ins_global_position +# TOPICS estimator_global_position +# TOPICS aux_global_position +``` + +At time of writing there is no format for documenting these.