1.3. Keyed Topics in ROS 2 Turtlesim Demo

1.3.1. Background

This use case explains how to run three turtlesim nodes by leveraging topic keys and content filtering for efficient communication.

  • Topic keys reduce the number of entities needed in the data flow, leading to more efficient resource and bandwidth usage.

  • Content Filter Topics allow subscribers to receive only the messages that match specific criteria, ensuring each Turtle Node processes only relevant data.

By integrating topic keys and content filtering, each turtle node processes the data intended for it. This setup illustrates efficient and effective communication in a complex system with multiple entities.

Users can control each turtle separately using the keyboard, while the graphical application visually represents their movements.

The controller receives the position of the turtles, which is determined by the ID of the turtle that publishes it, being this parameter the key in the message. Also, the controller publishes the velocity message to each corresponding turtle by the same means, using the ID of the turtle as the key in the message.

This mechanism allows ROS 2 nodes to control the history of messages with a different key separately and to avoid stepping on each other in the publisher and subscription history of samples.

The diagram below shows the entities required using topic keys:

../../../_images/keys.png

The diagram below shows the entities required without using topic keys. It is worth noting that the number of topics, subscriptions and publications required increases significantly as the system grows if we do not use the key based approach, increasing the memory footprint and resource usage.

../../../_images/non-keys.png

Note

Topic keys work exclusively with publishers and subscribers, not with services. Multiple service clients can use the same service, but there can only be one service server for a given service. Since each Turtle Node must have a service server to control goals, it does not make sense to have multiple clients (e.g., controllers) using the same service server with different keys.

1.3.2. Prerequisites

Familiarity with the following topics is recommended:

It is required to have previously installed Vulcanexus using one of the following installation methods:

1.3.3. Keyed Messages

The keyed Topics use the following message types to represent the turtles’ velocity and pose:

docs_turtlesim::msg::KeyedPose Represents the pose of a turtle with a key.

// KeyedPose.idl
module docs_turtlesim {
    module msg {
        struct KeyedPose {
            @key long turtle_id;        // Identifier of the turtle.
            double x;                   // X-coordinate of the turtles position.
            double y;                   // Y-coordinate of the turtles position.
            double theta;               // Orientation angle of the turtle.

            double linear_velocity;     // Linear velocity of the turtle.
            double angular_velocity;    // Angular velocity of the turtle.
        };
    };
};

docs_turtlesim::msg::KeyedVelocity Represents the velocity of a turtle with a key.

// KeyedTwist.idl
module docs_turtlesim {
    module msg {
        struct KeyedTwist {
            @key long turtle_id;                        // Identifier of the turtle.
            docs_turtlesim::msg::Vector3  linear;       // Linear velocity of the turtle.
            docs_turtlesim::msg::Vector3  angular;      // Angular velocity of the turtle.
        };
    };
};

1.3.4. Prepare the ROS 2 workspace

The ROS 2 package used in this use case is:

To create a new ROS 2 workspace and clone the docs_turtlesim package run:

mkdir -p $HOME/ros2-ws/src
cd $HOME/ros2-ws/src
git clone --depth=1 https://github.com/eProsima/vulcanexus.git tmp_dir
mv tmp_dir/code/turtlesim .
rm -rf tmp_dir

Build the ROS 2 workspace with:

cd $HOME/ros2-ws
colcon build

The resulting directory structure should look like this:

$HOME/ros2-ws/
├── build
├── install
├── log
└── src
    └── docs_turtlesim

1.3.5. Execution

First, it is necessary to setup the Vulcanexus environment and the ROS 2 workspace in all the terminals.

source /opt/vulcanexus/humble/setup.bash
source $HOME/ros2-ws/install/setup.bash

1.3.5.1. Run the controller application

To start the turtlesim controller, run:

ros2 run docs_turtlesim turtlesim_multi_control

1.3.5.2. Run the Turtlesim application

To launch the turtlesim application with three turtle nodes, use this command:

ros2 run docs_turtlesim turtlesim_node_keys

The turtlesim is now ready! Start by selecting a turtle by pressing its number ID (1, 2, or 3). Then, use the arrows to move the turtle around the screen. If the turtles move correctly, the system is working as expected.