Introduce message versions and ROS 2 translation node

Co-authored-by: bkueng <beat-kueng@gmx.net> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
PX4 · Jan 13, 2025 · 5c0b2d4 · 5c0b2d4
1 parent 1140acc
commit 5c0b2d4
Show file tree

Hide file tree

Showing 9 changed files with 675 additions and 2 deletions.
diff --git a/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.drawio b/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.drawio
diff --git a/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.svg b/assets/middleware/ros2/px4_ros2_interface_lib/translation_node.svg
diff --git a/en/SUMMARY.md b/en/SUMMARY.md
@@ -808,6 +808,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)

diff --git a/en/_sidebar.md b/en/_sidebar.md
@@ -797,6 +797,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)

diff --git a/en/middleware/uorb.md b/en/middleware/uorb.md
@@ -141,7 +141,33 @@ 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+)" />
+
+Message versioning has been in introduced in PX4 v1.16 (main) to make it easier to maintain compatibility between PX4 and ROS 2 versions.
+
+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 separately 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.
+
+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).
+
+::: note
+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}
 

diff --git a/en/releases/main.md b/en/releases/main.md
@@ -41,6 +41,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
   Mission commands that may take some time to complete, such as those for controlling gimbals, winches, and grippers, will progress to the next item when either feedback is received or the timeout expires.
   This is often used to provide a minimum delay for hardware that does not provide completion feedback, so that it can reach the commanded state before the mission progresses.
   ([PX4-Autopilot#23960](https://github.com/PX4/PX4-Autopilot/pull/23960)).
+- **[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
 
@@ -75,7 +76,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
 

diff --git a/en/ros2/index.md b/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