PX4 ROS 2 Message Translation Node

main (PX4 v1.16+) Experimental

The message translation node allows ROS 2 applications that were compiled against different versions of the PX4 messages to interwork with newer versions of PX4, and vice versa, without having to change either the application or the PX4 side.

Загальний огляд

The translation of messages from one definition version to another is possible thanks to the introduction of message versioning.

The translation node has access to all message versions previously defined by PX4. It dynamically observes the DDS data space, monitoring the publications, subscriptions and services originating from either PX4 via the uXRCE-DDS Bridge, or ROS 2 applications. When necessary, it converts messages to the current versions expected by both applications and PX4, ensuring compatibility.

To support the coexistence of different versions of the same messages within the ROS 2 domain, the ROS 2 topic-names for publications, subscriptions, and services include their respective message version as a suffix. This naming convention takes the form <topic_name>_v<version>, as shown in the diagram above.

Використання

Встановлення

The following steps describe how to install and run the translation node on your machine.

1. (Optional) Create a new ROS 2 workspace in which to build the message translation node and its dependencies:

   mkdir -p /path/to/ros_ws/src

2. Run the following helper script to copy the message definitions and translation node into your ROS workspace directory.

   cd /path/to/ros_ws
   /path/to/PX4-Autopilot/Tools/copy_to_ros_ws.sh .

3. Build and source the workspace.

   colcon build
   source /path/to/ros_ws/install/setup.bash

4. Finally, run the translation node.

   ros2 run translation_node translation_node_bin

   You should see an output similar to:

   [INFO] [1734525720.729530513] [translation_node]: Registered pub/sub topics and versions:
   [INFO] [1734525720.729594413] [translation_node]: Registered services and versions:

With the translation node running, any simultaneously running ROS 2 application designed to communicate with PX4 can do so, as long as it uses message versions recognized by the node. The translation node will print a warning if it encounters an unknown topic version.

INFO

After making a modification in PX4 to the message definitions and/or translation node code, you will need to rerun the steps above from point 2 to update your ROS workspace accordingly.

In ROS Applications

While developing a ROS 2 application that communicates with PX4, it is not necessary to know the specific version of a message being used. The message version can be added generically to a topic name like this:

topic_name + "_v" + std::to_string(T::MESSAGE_VERSION)

topic_name + "_v" + VehicleAttitude.MESSAGE_VERSION

where T is the message type, e.g. px4_msgs::msg::VehicleAttitude.

For example, the following implements a minimal subscriber and publisher node that uses two versioned PX4 messages and topics:

#include <string>
#include <rclcpp/rclcpp.hpp>
#include <px4_msgs/msg/vehicle_command.hpp>
#include <px4_msgs/msg/vehicle_attitude.hpp>

// Template function to get the message version suffix
// The correct message version is directly inferred from the message defintion
template <typename T>
std::string getMessageNameVersion() {
    if (T::MESSAGE_VERSION == 0) return "";
    return "_v" + std::to_string(T::MESSAGE_VERSION);
}

class MinimalPubSub : public rclcpp::Node {
  public:
    MinimalPubSub() : Node("minimal_pub_sub") {
      // Use template function to define the correct topics automatically
      const std::string sub_topic = "/fmu/out/vehicle_attitude" + getMessageNameVersion<px4_msgs::msg::VehicleAttitude>();
      const std::string pub_topic = "/fmu/in/vehicle_command" + getMessageNameVersion<px4_msgs::msg::VehicleCommand>();

      _subscription = this->create_subscription<px4_msgs::msg::VehicleAttitude>(
          sub_topic, 10,
          std::bind(&MinimalPubSub::attitude_callback, this, std::placeholders::_1));
      _publisher = this->create_publisher<px4_msgs::msg::VehicleCommand>(pub_topic, 10);
    }

  private:
    void attitude_callback(const px4_msgs::msg::VehicleAttitude::SharedPtr msg) {
      RCLCPP_INFO(this->get_logger(), "Received attitude message.");
    }

    rclcpp::Publisher<px4_msgs::msg::VehicleCommand>::SharedPtr _publisher;
    rclcpp::Subscription<px4_msgs::msg::VehicleAttitude>::SharedPtr _subscription;
};

import rclpy
from rclpy.node import Node
from px4_msgs.msg import VehicleCommand, VehicleAttitude

# Helper function to get the message version suffix
# The correct message version is directly inferred from the message definition
def get_message_name_version(msg_class):
    if msg_class.MESSAGE_VERSION == 0:
        return ""
    return f"_v{msg_class.MESSAGE_VERSION}"

class MinimalPubSub(Node):
    def __init__(self):
        super().__init__('minimal_pub_sub')

        # Use helper function to define the correct topics automatically
        sub_topic = f"/fmu/out/vehicle_attitude{get_message_name_version(VehicleAttitude)}"
        pub_topic = f"/fmu/in/vehicle_command{get_message_name_version(VehicleCommand)}"

        self._subscription = self.create_subscription(
            VehicleAttitude,
            sub_topic,
            self.attitude_callback,
            10
        )

        self._publisher = self.create_publisher(
            VehicleCommand,
            pub_topic,
            10
        )

    def attitude_callback(self, msg):
        self.get_logger().info("Received attitude message.")

On the PX4 side, the DDS client automatically adds the version suffix if a message definition contains the field uint32 MESSAGE_VERSION = x.

INFO

Version 0 of a topic means that no _v<version> suffix should be added.

Development

Означення

A message defines the data format used for communication, whether over a topic or a service. Therefore a message can be either a topic message defined by a .msg file, or a service message defined by a .srv file.

A versioned message is a message for which changes are tracked and each change results in a version bump, with the previous state of the definition being stored in history. The latest version of every message is stored in msg/versioned/ for topics (or srv/versioned for services), and all older versions are stored in msg/px4_msgs_old/msg/ (or msg/px4_msgs_old/srv/).

A version translation defines a bidirectional mapping of the contents of one or more message definition across different versions. Each translation is stored as a separate .h header file under msg/translation_node/translations/. Message translations can be either direct or generic.

• A direct translation defines a bidirectional mapping of the contents of a single message between two of its versions. This is the simpler case and should be preferred if possible.
• A generic translation defines a bidirectional mapping of the contents of n input messages to m output messages across different versions. This can be used for merging or splitting a message, or when moving a field from one message to another.

File Structure

Starting from PX4 v1.16 (main), the PX4-Autopilot msg/ and srv/ directories are structured as follows:

PX4-Autopilot
├── ...
├── msg/
  ├── *.msg              # Non-versioned topic message files
  ├── versioned/         # Latest versioned topic message files
  ├── px4_msgs_old/      # History of versioned messages (.msg + .srv) [ROS 2 package]
  └── translation_node/  # Translation node and translation headers [ROS 2 package]
└── srv/
  ├── *.srv              # Non-versioned service message files
  └── versioned/         # Latest versioned service message files

This structure introduces new directories: versioned/, px4_msgs_old/, and translation_node/.

Directories msg/versioned/ and srv/versioned/

• Contain the current latest version of each message.
• Files in these directories must include a MESSAGE_VERSION field to indicate that they are versioned.
• File names follow the conventional naming scheme (without a version suffix).

Example directory structure:

PX4-Autopilot
├── ...
├── msg/
  └── versioned/
    ├── VehicleAttitude.msg        # e.g. MESSAGE_VERSION = 3
    └── VehicleGlobalPosition.msg  # e.g. MESSAGE_VERSION = 2
└── srv/
  └── versioned/
    └── VehicleCommand.srv         # e.g. MESSAGE_VERSION = 2

Directory px4_msgs_old/

• Archives the history of all versioned messages, including both topic and service messages (resp. under msg/ and srv/ subdirectories).
• Each file includes a MESSAGE_VERSION field.
• File names reflect the message's version with a suffix (e.g., V1, V2).

Example directory structure (matching the example above):

  ...
  msg/
  └── px4_msgs_old/
    ├── msg/
      ├── VehicleAttitudeV1.msg
      ├── VehicleAttitudeV2.msg
      └── VehicleGlobalPositionV1.msg
    └── srv/
      └── VehicleCommandV1.srv

Directory translation_node/

• Contains headers for translating between all different versions of messages.
• 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 (matching the example above):

  ...
  msg/
  └── translation_node/
    └── translations/
      ├── 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 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.

The example describes the process of updating the VehicleAttitude message definition to contain an additional new_field entry, incrementing the message version from 3 to 4, and creating a new direct translation in the process.

1. Create an Archived Definition of the Current Versioned Message

   Copy the versioned .msg topic message file (or .srv service message file) to px4_msgs_old/msg/ (or px4_msgs_old/srv/), and append its message version to the file name.

   For example:
   Copy msg/versioned/VehicleAttitude.msg → msg/versioned/px4_msgs_old/msg/VehicleAttitudeV3.msg

2. Update Translation References to the Archived Definition

   Update the existing translations header files msg/translation_node/translations/*.h to reference the newly archived message definition.

   For example, update references in those files:
   

   • Replace px4_msgs::msg::VehicleAttitude → px4_msgs_old::msg::VehicleAttitudeV3
   • Replace #include <px4_msgs/msg/vehicle_attitude.hpp> → #include <px4_msgs_old/msg/vehicle_attitude_v3.hpp>

3. Update the Versioned Definition

   Update the versioned .msg topic message file (or .srv service message file) with required changes.

   First increment the MESSAGE_VERSION field. Then update the message fields that prompted the version change.

   For example, update msg/versioned/VehicleAttitude.msg from:

   uint32 MESSAGE_VERSION = 3
   uint64 timestamp
   ...

   to

   uint32 MESSAGE_VERSION = 4  # Increment
   uint64 timestamp
   float32 new_field           # Make definition changes
   ...

4. Add a New Translation Header

   Add a new version translation to bridge the archived version and the updated current version, by creating a new translation header.

   For example, create a direct translation header translation_node/translations/translation_vehicle_attitude_v4.h:

   // Translate VehicleAttitude v3 <--> v4
   #include <px4_msgs_old/msg/vehicle_attitude_v3.hpp>
   #include <px4_msgs/msg/vehicle_attitude.hpp>
   
   class VehicleAttitudeV4Translation {
   public:
     using MessageOlder = px4_msgs_old::msg::VehicleAttitudeV3;
     static_assert(MessageOlder::MESSAGE_VERSION == 3);
   
     using MessageNewer = px4_msgs::msg::VehicleAttitude;
     static_assert(MessageNewer::MESSAGE_VERSION == 4);
   
     static constexpr const char* kTopic = "fmu/out/vehicle_attitude";
   
     static void fromOlder(const MessageOlder &msg_older, MessageNewer &msg_newer) {
       msg_newer.timestamp = msg_older.timestamp;
       msg_newer.timestamp_sample = msg_older.timestamp_sample;
       msg_newer.q[0] = msg_older.q[0];
       msg_newer.q[1] = msg_older.q[1];
       msg_newer.q[2] = msg_older.q[2];
       msg_newer.q[3] = msg_older.q[3];
       msg_newer.delta_q_reset = msg_older.delta_q_reset;
       msg_newer.quat_reset_counter = msg_older.quat_reset_counter;
   
       // Populate `new_field` with some value
       msg_newer.new_field = -1;
     }
   
     static void toOlder(const MessageNewer &msg_newer, MessageOlder &msg_older) {
       msg_older.timestamp = msg_newer.timestamp;
       msg_older.timestamp_sample = msg_newer.timestamp_sample;
       msg_older.q[0] = msg_newer.q[0];
       msg_older.q[1] = msg_newer.q[1];
       msg_older.q[2] = msg_newer.q[2];
       msg_older.q[3] = msg_newer.q[3];
       msg_older.delta_q_reset = msg_newer.delta_q_reset;
       msg_older.quat_reset_counter = msg_newer.quat_reset_counter;
   
       // Discards `new_field` from MessageNewer
     }
   };
   
   REGISTER_TOPIC_TRANSLATION_DIRECT(VehicleAttitudeV4Translation);

   Version translation templates are provided here:

   • Direct Topic Message Translation Template
   • Generic Topic Message Translation Template
   • Direct Service Message Translation Template

5. Include New Headers in all_translations.h

   Add all newly created headers to translations/all_translations.h so that the translation node can find them.

   For example, append the following line to all_translation.h:

   #include "translation_vehicle_attitude_v4.h"

Note that in the example above and in most cases, step 4 only requires the developer to create a direct translation for the definition change. This is because the changes only involved a single message. In more complex cases of splitting, merging and/or moving definitions then a generic translation must be created.

For example when moving a field from one message to another, a single generic translation should be added with the two older message versions as input, and the two newer versions as output. This ensures there is no information lost when translating forward or backward.

This is exactly the approach shown by the Generic Topic Message Translation Template, omitting only the code for actually modifying fields in the fromOlder() and toOlder() methods.

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 if it were versioned. This is primarily important for services which are more likely reference other message definitions.

Implementation Details

The translation node dynamically monitors the topics and services. It then instantiates the counterside of the publications and subscribers as required. For example if there is an external publisher for version 1 of a topic and subscriber for version 2.

Internally, it maintains a graph of all known topic and version tuples (which are the graph nodes). The graph is connected by the message translations. As arbitrary message translations can be registered, the graph can have cycles and multiple paths from one node to another. Therefore on a topic update, the graph is traversed using a shortest path algorithm. When moving from one node to the next, the message translation method is called with the current topic data. If a node contains an instantiated publisher (because it previously detected an external subscriber), the data is published. Thus, multiple subscribers of any version of the topic can be updated with the correct version of the data.

For translations with multiple input topics, the translation continues once all input messages are available.

Обмеження

• Translation of service messages does not work on ROS Humble, but does on ROS Jazzy. This is because the current implementation depends on a service API that is not yet available in ROS Humble. Translation of topic messages is fully supported.

• Services messages only support a linear history, i.e. no message splitting or merging.

• Having both publishers and subscribers for two different versions of the same topic is currently not handled by the translation node and would trigger infinite circular publications. This refers to the following problematic configuration:

  app 1: pub topic_v1, sub topic_v1
  app 2: pub topic_v2, sub topic_v2

  In practice this configuration is unlikely to occur because ROS topics shared with the FMU are intended to be directional (e.g. /fmu/out/vehicle_status or /fmu/in/trajectory_setpoint), therefore apps typically do not publish and subscribe simultaneously to the same topic. The translation node could be extended to handle this corner-case if required.

Original document with requirements: https://docs.google.com/document/d/18_RxV1eEjt4haaa5QkFZAlIAJNv9w5HED2aUEiG7PVQ/edit?usp=sharing