diff --git a/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.drawio b/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.drawio
index fb29d3fd3503..267e415997b8 100644
--- a/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.drawio
+++ b/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.drawio
@@ -91,7 +91,7 @@
-
+
diff --git a/en/middleware/uorb.md b/en/middleware/uorb.md
index 373bdc2b55fb..9c3c07c7894d 100644
--- a/en/middleware/uorb.md
+++ b/en/middleware/uorb.md
@@ -145,17 +145,20 @@ The full API is documented in [platforms/common/uORB/uORBManager.hpp](https://gi
-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).
diff --git a/en/ros2/px4_ros2_msg_translation_node.md b/en/ros2/px4_ros2_msg_translation_node.md
index d4594479fa61..ce0c1bd58570 100644
--- a/en/ros2/px4_ros2_msg_translation_node.md
+++ b/en/ros2/px4_ros2_msg_translation_node.md
@@ -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:
+ Version translation templates are provided here:
- [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`**
+
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.