Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
apply review suggestion 05
Browse files Browse the repository at this point in the history
GuillaumeLaine committed Jan 9, 2025
1 parent 607fe48 commit 64154f8
Showing 3 changed files with 27 additions and 23 deletions.
Original file line number Diff line number Diff line change
@@ -91,7 +91,7 @@
<mxCell id="uqWdyP-RkQtU8MaK-FNy-32" value="&lt;span style=&quot;font-size: 18px; font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; text-align: center; white-space-collapse: preserve; background-color: transparent; font-family: &amp;quot;Roboto Condensed&amp;quot;, sans-serif; color: rgb(28, 69, 135); font-weight: 700; vertical-align: baseline;&quot;&gt; FAST-&lt;/span&gt;&lt;span style=&quot;font-size: 18px; font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; text-align: center; white-space-collapse: preserve; background-color: transparent; font-family: &amp;quot;Roboto Condensed&amp;quot;, sans-serif; color: rgb(61, 133, 198); font-weight: 700; vertical-align: baseline;&quot;&gt;DDS&lt;/span&gt;" style="rounded=0;whiteSpace=wrap;html=1;align=left;verticalAlign=bottom;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;shadow=1;" parent="1" vertex="1">
<mxGeometry x="120" y="590" width="720" height="200" as="geometry" />
</mxCell>
<mxCell id="uqWdyP-RkQtU8MaK-FNy-33" value="uXRCE-DDS&lt;div&gt;&lt;b&gt;agent&lt;/b&gt;&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxCell id="uqWdyP-RkQtU8MaK-FNy-33" value="&lt;span style=&quot;font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; white-space-collapse: preserve; font-family: Arial, sans-serif; color: rgb(32, 33, 36); background-color: rgb(255, 255, 255); vertical-align: baseline;&quot;&gt;μ&lt;/span&gt;&lt;span style=&quot;font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; white-space-collapse: preserve; background-color: transparent; font-family: &amp;quot;Roboto Condensed&amp;quot;, sans-serif; color: rgb(28, 69, 135); font-weight: 700; vertical-align: baseline;&quot;&gt;XRCE-&lt;/span&gt;&lt;span style=&quot;font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; white-space-collapse: preserve; background-color: transparent; font-family: &amp;quot;Roboto Condensed&amp;quot;, sans-serif; color: rgb(61, 133, 198); font-weight: 700; vertical-align: baseline;&quot;&gt;DDS&lt;/span&gt;&lt;span style=&quot;color: rgb(0, 0, 0); font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; white-space-collapse: preserve; background-color: transparent; font-family: &amp;quot;Roboto Condensed&amp;quot;, sans-serif; font-weight: 700; vertical-align: baseline;&quot;&gt;&lt;br&gt;&lt;/span&gt;&lt;span style=&quot;color: rgb(0, 0, 0); font-variant-numeric: normal; font-variant-east-asian: normal; font-variant-alternates: normal; font-variant-position: normal; font-variant-emoji: normal; white-space-collapse: preserve; background-color: transparent; font-family: &amp;quot;Roboto Condensed&amp;quot;, sans-serif; font-weight: 700; vertical-align: baseline;&quot;&gt;agent&lt;/span&gt;" style="rounded=0;whiteSpace=wrap;html=1;" parent="1" vertex="1">
<mxGeometry x="140" y="610" width="80" height="150" as="geometry" />
</mxCell>
<mxCell id="uqWdyP-RkQtU8MaK-FNy-37" value="ROS 2&lt;div&gt;Message&lt;/div&gt;&lt;div&gt;Translation&lt;/div&gt;&lt;div&gt;Node&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;" parent="1" vertex="1">
15 changes: 9 additions & 6 deletions en/middleware/uorb.md
Original file line number Diff line number Diff line change
@@ -145,17 +145,20 @@ The full API is documented in [platforms/common/uORB/uORBManager.hpp](https://gi

<Badge type="tip" text="main (PX4 v1.16+)" />

Message versioning has been in introduced in PX4 v1.16 to make it easier to maintain compatibility between PX4 and ROS 2 versions.
Message versioning has been in introduced in PX4 v1.16 (main) to make it easier to maintain compatibility between PX4 and ROS 2 versions.

This versioning mechanism supports the [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md), which enables seamless communication between PX4 and ROS 2 applications; when different versions of message definitions are in use, the ROS 2 translation node ensures that messages can be converted and exchanged correctly.
Versioned messages include an additional field `uint32 MESSAGE_VERSION = x`, where `x` corresponds to the current version of the message.
Versioned message files are stored separetly from their non-versioned counterpart.
Topic message files are located under `msg/versioned` and service message files are located under `srv/versioned`.
Non-versioned messages remain in the `msg/` and `srv/` directories respectively.

Versioned messages are stored in the `msg/versioned/` directory (distinct from their non-versioned counterparts, which reside directly in the `msg/` directory).
Each versioned message definition includes an additional field: `uint32 MESSAGE_VERSION = X`, where `X` corresponds to the current version of the message.
When a versioned message definition is modified, the version number should be incremented to reflect changes in its structure or semantics.
Additionally, [message translations](../ros2/px4_ros2_msg_translation_node.md#updating-a-message) must also be updated for versioned messages, in order to convert from the old version to the new structure.
This versioning mechanism supports the [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md), which enables seamless communication between PX4 and ROS 2 applications; when different versions of message definitions are in use, the ROS 2 translation node ensures that messages can be converted and exchanged correctly.

Versioned messages are designed to remain more stable over time compared to their non-versioned counterparts, as they are intended to be used across multiple releases of PX4 and external systems, ensuring greater compatibility over longer periods.

Updating a versioned message involves more steps compared to updating a non-versioned one.
Please see the section on [Updating a Versioned Message](../ros2/px4_ros2_msg_translation_node.md#updating-a-versioned-message).

For the full list of versioned and non-versioned messages, refer to the [uORB Message Reference](../msg_docs/index.md).

For more on PX4 and ROS 2 communication, refer to the page about the [PX4-ROS 2 Bridge](../ros/ros2_comm.md).
33 changes: 17 additions & 16 deletions en/ros2/px4_ros2_msg_translation_node.md
Original file line number Diff line number Diff line change
@@ -132,7 +132,7 @@ This can be used for merging or splitting a message, or when moving a field from
### File Structure
Starting from PX4 v1.16, the PX4-Autopilot `msg/` and `srv/` directories are structured as follows:
Starting from PX4 v1.16 (main), the PX4-Autopilot `msg/` and `srv/` directories are structured as follows:
```
PX4-Autopilot
@@ -175,7 +175,7 @@ PX4-Autopilot
- Each file includes a `MESSAGE_VERSION` field.
- File names reflect the message's version with a suffix (e.g., `V1`, `V2`).
Example directory structure:
Example directory structure (coherant with example above):
```
...
@@ -195,24 +195,24 @@ Example directory structure:
- Each translation (direct or generic) is a single `.h` header file.
- The header `all_translation.h` acts as the main header, and includes all subsequent translation headers.
Example directory structure following the example above:
Example directory structure (coherant with example above):
```
...
msg/
└── translation_node/
└── translations/
├── all_translations.h # Main header
├── vehicle_attitude_v1.h # Direct translation v0 <-> v1
├── vehicle_attitude_v2.h # Direct translation v1 <-> v2
├── vehicle_attitude_v3.h # Direct translation v2 <-> latest (v3)
├── vehicle_global_position_v1.h # Direct translation v0 <-> v1
├── vehicle_global_position_v2.h # Direct translation v1 <-> latest (v2)
├── vehicle_command_v1.h # Direct translation v0 <-> v1
└── vehicle_command_v2.h # Direct translation v1 <-> latest (v2)
├── all_translations.h # Main header
├── translation_vehicle_attitude_v1.h # Direct translation v0 <-> v1
├── translation_vehicle_attitude_v2.h # Direct translation v1 <-> v2
├── translation_vehicle_attitude_v3.h # Direct translation v2 <-> latest (v3)
├── translation_vehicle_global_position_v1.h # Direct translation v0 <-> v1
├── translation_vehicle_global_position_v2.h # Direct translation v1 <-> latest (v2)
├── translation_vehicle_command_v1.h # Direct translation v0 <-> v1
└── translation_vehicle_command_v2.h # Direct translation v1 <-> latest (v2)
```
### Updating a Message
### Updating a Versioned Message
This section provides a step-by-step walkthrough and a basic working example of what the process of changing a versioned message looks like.
@@ -260,7 +260,7 @@ The example describes the process of updating the `VehicleAttitude` message defi
Add a new version translation to bridge the archived version and the new version, by creating a new translation header.
For example, create a direct translation header `translation_node/translations/vehicle_attitude_v4.h`:
For example, create a direct translation header `translation_node/translations/translation_vehicle_attitude_v4.h`:
```c++
// Translate VehicleAttitude v3 <--> v4
@@ -308,13 +308,14 @@ The example describes the process of updating the `VehicleAttitude` message defi
REGISTER_TOPIC_TRANSLATION_DIRECT(VehicleAttitudeV4Translation);
```
Version translation templates are provided here: <!-- (TODO: update GitHub urls) -->
Version translation templates are provided here: <!-- TODO: update GitHub urls -->
- [Direct Message Translation Template](https://github.com/PX4/PX4-Autopilot/blob/message_versioning_and_translation/msg/translation_node/translations/example_translation_direct_v1.h)
- [Generic Message Translation Template](https://github.com/PX4/PX4-Autopilot/blob/message_versioning_and_translation/msg/translation_node/translations/example_translation_multi_v2.h)
- [Direct Service Translation Template](https://github.com/PX4/PX4-Autopilot/blob/message_versioning_and_translation/msg/translation_node/translations/example_translation_service_v1.h)
5. **Include New Headers in `all_translations.h`**
<!-- TODO: update GitHub url -->
Add all newly created headers to [`translations/all_translations.h`](https://github.com/PX4/PX4-Autopilot/blob/message_versioning_and_translation/msg/translation_node/translations/all_translations.h) so that the translation node can find them.
For example, append the following line to `all_translation.h`:
@@ -333,7 +334,7 @@ This ensures there is no information lost when translating forward or backward.
::: warning
If a nested message definition changes, all messages including that message also require a version update.
For example this would be the case for message [PositionSetpointTriplet](../msg_docs/PositionSetpointTriplet.md) if it were versioned.
This is primarily important for services which often reference other message definitions.
This is primarily important for services which are more likely reference other message definitions.
:::
## Implementation Details
@@ -355,7 +356,7 @@ For translations with multiple input topics, the translation continues once all
## Limitations
- The current implementation depends on a service API that is not yet available in ROS Humble, and therefore does not support services when built for ROS Humble.
- Services only support a linear history, i.e. no message splitting or merging
- Services only support a linear history, i.e. no message splitting or merging.
- Having both publishers and subscribers for two different versions of a topic is currently not handled by the translation node and would trigger infinite circular publications.
This could be extended if required.

0 comments on commit 64154f8

Please sign in to comment.