From a0c25d8f753fcdc06268cc82c7fc6ec0840ec315 Mon Sep 17 00:00:00 2001 From: GuillaumeLaine Date: Wed, 20 Nov 2024 16:13:50 +0100 Subject: [PATCH] WIP: message versioning --- en/middleware/uorb.md | 17 +++++++++++++++++ en/ros2/user_guide.md | 5 ++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/en/middleware/uorb.md b/en/middleware/uorb.md index 93a43ca716af7..a0578915e53d3 100644 --- a/en/middleware/uorb.md +++ b/en/middleware/uorb.md @@ -141,10 +141,27 @@ 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 +Starting from PX4 version x.x.x, message versioning was introduced to address the challenges of maintaining compatibility across systems where different versions of message definitions may be in use, such as between PX4 and external systems like ROS 2. + +Versioned messages are stored in the `msg/versioned/` directory, distinct from their to their non-versioned counterparts, which reside 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. + +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. + +This versioning mechanism supports the ROS 2 message translation system (TODO: add link), which enables seamless communication between PX4 and ROS 2 applications. +When different versions of message definitions are in use, the translation system ensures that messages can be converted and exchanged correctly. + +For the full list of versioned and non-versioned messages, refer to the full [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). ## Message/Field Deprecation {#deprecation} +(Is any of this still relevant? Not seeing deprecated fields or msgs in latest PX4) + 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: - Changing existing fields or messages that external tools rely on is generally acceptable if there are good reasons for the update. diff --git a/en/ros2/user_guide.md b/en/ros2/user_guide.md index 6c3bd3f1684f9..f99f5c89ced2a 100644 --- a/en/ros2/user_guide.md +++ b/en/ros2/user_guide.md @@ -32,7 +32,10 @@ The subset of uORB messages that are generated into the client are listed in [PX The generator uses the uORB message definitions in the source tree: [PX4-Autopilot/msg](https://github.com/PX4/PX4-Autopilot/tree/main/msg) to create the code for sending ROS 2 messages. ROS 2 applications need to be built in a workspace that has the _same_ message definitions that were used to create the uXRCE-DDS client module in the PX4 Firmware. -You can include these by cloning the interface package [PX4/px4_msgs](https://github.com/PX4/px4_msgs) into your ROS 2 workspace (branches in the repo correspond to the messages for different PX4 releases). +You can include these by cloning the interface package [PX4/px4_msgs](https://github.com/PX4/px4_msgs) into your ROS 2 workspace (branches in the repo correspond to the messages for different PX4 releases). (Add message versioning comment) + +Starting from PX4 x.x.x in which [message versioning](../middleware/uorb.md#message-versioning) was introduced, ROS2 applications may use a different version of message definitions than those used to build PX4. +However this will require the ROS 2 translation node (TODO: add link) to be running to ensure that messages can be converted and exchanged correctly. Note that the micro XRCE-DDS _agent_ itself has no dependency on client-side code. It can be built from [source](https://github.com/eProsima/Micro-XRCE-DDS-Agent) either standalone or as part of a ROS build, or installed as a snap.