Message versioning and ROS 2 message translation

en/SUMMARY.md

@@ -809,6 +809,7 @@
     - [PX4 ROS 2 Interface Library](ros2/px4_ros2_interface_lib.md)
       - [Control Interface](ros2/px4_ros2_control_interface.md)
       - [Navigation Interface](ros2/px4_ros2_navigation_interface.md)
+    - [ROS 2 Message Translation Node](ros2/px4_ros2_msg_translation_node.md)
   - [ROS 1 (Deprecated)](ros/ros1.md)
     - [ROS/MAVROS Installation Guide](ros/mavros_installation.md)
     - [ROS/MAVROS Offboard Example (C++)](ros/mavros_offboard_cpp.md)

en/_sidebar.md

@@ -798,6 +798,7 @@
     - [PX4 ROS 2 Interface Library](/ros2/px4_ros2_interface_lib.md)
       - [Control Interface](/ros2/px4_ros2_control_interface.md)
       - [Navigation Interface](/ros2/px4_ros2_navigation_interface.md)
+    - [ROS 2 Message Translation Node](/ros2/px4_ros2_msg_translation_node.md)
   - [ROS 1 (Deprecated)](/ros/ros1.md)
     - [ROS/MAVROS Installation Guide](/ros/mavros_installation.md)
     - [ROS/MAVROS Offboard Example (C++)](/ros/mavros_offboard_cpp.md)

en/middleware/uorb.md

@@ -141,7 +141,40 @@ Make sure not to mix `orb_advertise_multi` and `orb_advertise` for the same topi
 
 The full API is documented in [platforms/common/uORB/uORBManager.hpp](https://github.com/PX4/PX4-Autopilot/blob/main/platforms/common/uORB/uORBManager.hpp).
 
+## Message Versioning
 
+<Badge type="tip" text="main (PX4 v1.16+)" />
+
+Optional message versioning was introduced in PX4 v1.16 (main) to make it easier to maintain compatibility between PX4 and ROS 2 versions compiled against different message definitions.
+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.
+
+Versioned messages include an additional field `uint32 MESSAGE_VERSION = x`, where `x` corresponds to the current version of the message.
+
+Versioned and non-versioned messages are separated in the file system:
+
+- Non-versioned topic message files and service message files remain in the [`msg/`](https://github.com/PX4/PX4-Autopilot/tree/main/msg) and [`srv/`](https://github.com/PX4/PX4-Autopilot/tree/main/srv) directories, respectively.
+- The current (highest) version of message files are located in the `versioned` subfolders ([`msg/versioned`](https://github.com/PX4/PX4-Autopilot/tree/main/msg/versioned) and [`srv/versioned`](https://github.com/PX4/PX4-Autopilot/tree/main/srv/versioned)).
+- Older versions of messages are stored in nested `px4_msgs_old/msg/` subfolders ([`msg/versioned/px4_msgs_old/msg/`](https://github.com/PX4/PX4-Autopilot/tree/main/msg/versioned/px4_msgs_old/msg) and [`srv/versioned`](https://github.com/PX4/PX4-Autopilot/tree/main/srv/versioned/px4_msgs_old/srv/)).
+  The files are also renamed with a suffix to indicate their version number.
+
+::: tip
+The file structure is outlined in more detail in [File structure (ROS 2 Message Translation Node)](../ros2/px4_ros2_msg_translation_node.md#file-structure).
+:::
+
+The [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md) uses the above message definitions to seamlessly convert messages sent between PX4 and ROS 2 applications that have been compiled against different message versions.
+
+Updating a versioned message involves more steps compared to updating a non-versioned one.
+For more information see [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 see: [uORB Message Reference](../msg_docs/index.md).
+
+For more on PX4 and ROS 2 communication, see [PX4-ROS 2 Bridge](../ros/ros2_comm.md).
+
+::: info
+ROS 2 plans to natively support message versioning in the future, but this is not implememented yet.
+See the related ROS Enhancement Proposal ([REP 2011](https://github.com/ros-infrastructure/rep/pull/358)).
+See also this [Foxglove post](https://foxglove.dev/blog/sending-ros2-message-types-over-the-wire) on message hashing and type fetching.
+:::
 
 ## Message/Field Deprecation {#deprecation}
 

en/releases/main.md

@@ -44,6 +44,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
 - [Compass calibration for large vehicles](../config/compass.md#large-vehicle-calibration).
   This method is designed for vehicles where full rotation is impractical or impossible.
   ([PX4-Autopilot#23185](https://github.com/PX4/PX4-Autopilot/pull/23185)).
+- **[uORB]** Introduce a [version field](../middleware/uorb.md#message-versioning) for a subset of uORB messages ([PX4-Autopilot#23850](https://github.com/PX4/PX4-Autopilot/pull/23850))
 
 ### Control
 
@@ -84,7 +85,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
 
 ### uXRCE-DDS / ROS2
 
-- TBD
+- **[Feature]** <Badge type="warning" text="Experimental"/> [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md) to translate PX4 messages from one defintion version to another dynamically ([PX4-Autopilot#24113](https://github.com/PX4/PX4-Autopilot/pull/24113))
 
 ### MAVLink
 

en/ros2/index.md

@@ -37,6 +37,7 @@ The main topics in this section are:
 - [ROS 2 Multi Vehicle Simulation](../ros2/multi_vehicle.md): Instructions for connecting to multipole PX4 simulations via single ROS 2 agent.
 - [PX4 ROS 2 Interface Library](../ros2/px4_ros2_interface_lib.md): A C++ library that simplies interacting with PX4 from ROS 2.
   Can be used to create and register flight modes wrtten using ROS2 and send position estimates from ROS2 applications such as a VIO system.
+- [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md): A ROS 2 message translation node that enables communcation between PX4 and ROS 2 applications that were compiled with different sets of messages versions.
 
 ## Further Information