From 503c3472872a6fd99d1b24525ba3b8fc6ca77102 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 4 Jun 2025 15:27:31 +1000 Subject: [PATCH 1/2] Add ORB_QUEUE_LENGTH info --- docs/en/middleware/uorb.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/en/middleware/uorb.md b/docs/en/middleware/uorb.md index a164abadae22..3f28203f7d83 100644 --- a/docs/en/middleware/uorb.md +++ b/docs/en/middleware/uorb.md @@ -61,12 +61,12 @@ For example the [VelocityLimits](../msg_docs/VelocityLimits.md) message definiti ```text # Velocity and yaw rate limits for a multicopter position slow mode only -uint64 timestamp # time since system start (microseconds) +uint64 timestamp # [us] Time since system start. # absolute speeds, NAN means use default limit -float32 horizontal_velocity # [m/s] -float32 vertical_velocity # [m/s] -float32 yaw_rate # [rad/s] +float32 horizontal_velocity # [m/s] Horizontal velocity. +float32 vertical_velocity # [m/s] Vertical velocity. +float32 yaw_rate # [rad/s] Yaw rate. ``` By default this message definition will be compiled to a single topic with an id `velocity_limits`, a direct conversion from the CamelCase name to a snake_case version. @@ -92,15 +92,30 @@ To nest a message, simply include the nested message type in the parent message ```text # 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) +uint64 timestamp # [us] Time since system start. PositionSetpoint previous PositionSetpoint current PositionSetpoint next ``` +### uORB Buffer Length + +uORB messages have a single buffer by default, which may be overwritten if the message publication rate is too high. +Subscribers will then be able to read up to four messages in sequence before losing information, rather than just the last one sent. + +You can create a message buffer using the named constant `ORB_QUEUE_LENGTH`. +The value is the length of the queue, which must be a power of 2 (so 2, 4, 8, ...). + +For example, to create a four-message queue, add the following line to your message definition: + +```sh +uint8 ORB_QUEUE_LENGTH = 4 +``` + ### Message/Field Deprecation {#deprecation} As there are external tools using uORB messages from log files, such as [Flight Review](https://github.com/PX4/flight_review), certain aspects need to be considered when updating existing messages: From 583b7700b89bfbd97f0264c6503e6c4ef6192825 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 11 Jun 2025 17:49:51 +1000 Subject: [PATCH 2/2] Clarify how the queue works --- docs/en/middleware/uorb.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/en/middleware/uorb.md b/docs/en/middleware/uorb.md index 3f28203f7d83..ebd6a592df9d 100644 --- a/docs/en/middleware/uorb.md +++ b/docs/en/middleware/uorb.md @@ -102,20 +102,24 @@ PositionSetpoint current PositionSetpoint next ``` -### uORB Buffer Length +### uORB Buffer Length (ORB_QUEUE_LENGTH) -uORB messages have a single buffer by default, which may be overwritten if the message publication rate is too high. -Subscribers will then be able to read up to four messages in sequence before losing information, rather than just the last one sent. - -You can create a message buffer using the named constant `ORB_QUEUE_LENGTH`. -The value is the length of the queue, which must be a power of 2 (so 2, 4, 8, ...). +uORB messages have a single-message buffer by default, which may be overwritten if the message publication rate is too high. +In most cases this does not matter: either we are only interested in the latest sample of a topic, such as a sensor value or a setpoint, or losing a few samples is not a particular problem. +For relatively few cases, such as vehicle commands, it is important that we don't drop topics. +In order to reduce the chance that messages will be dropped we can use named constant `ORB_QUEUE_LENGTH` to create a buffer of the specified length. For example, to create a four-message queue, add the following line to your message definition: ```sh uint8 ORB_QUEUE_LENGTH = 4 ``` +As long as subscribers are able to read messages out of the buffer quickly enough than it isn't ever fully filled to the queue length (by publishers), they will be able to get all messages that are sent. +Messages will still be lost they are published when the queue is filled. + +Note that the queue length value must be a power of 2 (so 2, 4, 8, ...). + ### Message/Field Deprecation {#deprecation} As there are external tools using uORB messages from log files, such as [Flight Review](https://github.com/PX4/flight_review), certain aspects need to be considered when updating existing messages: