Exchange Messages with ROS 2
Send a Holoscan graph’s output to an existing ROS 2 node and receive that node’s messages back into the graph.
✨ Agent prompt: Exchange messages with ROS 2
Before you start
- You have a C++ Holoscan graph, with the
isaac::common::ros2_bridgelibrary and ROS 2 (rclcppplus your message packages) available to your build. Inside the Isaac OS repository, Build and run covers this. From your own project, see Integrate in your project. - Your graph and the ROS 2 node run on the same host, with the same
ROS_DOMAIN_IDand, if you set it, the sameRMW_IMPLEMENTATION. - The ROS 2 node’s QoS is compatible with the bridge topic’s QoS, which defaults to reliable, volatile, keep last 10. To change it, see Match a node’s QoS.
The steps below are taken from the runnable ROS 2 bridge reference, which publishes a pose, has an external ROS 2 node relay it, and receives it back.
Connect the graph
Create the bridge
The string names the rclcpp::Node the bridge runs under:
Wire ports to topics
Give your graph a reference to the bridge:
Then declare a default clock, which compile() requires, and wire ports in compose().
to_ros2 publishes an operator Output to a ROS 2 topic. from_ros2 delivers a ROS 2 topic to
an operator Input:
The reference app’s ReferenceGraph shows the complete class.
Compile, start the bridge, then run
Compile the graph, start the bridge with the plan’s endpoint catalog, then run the graph.
start() initializes rclcpp for the process, so create any other in-process ROS 2 node
after it:
Stop the graph, then the bridge
When you are done, stop the graph first and the bridge second:
Check that it works
Run your app and, from a second ROS 2 shell, check the rate of each bridged topic:
Use ros2 topic echo <topic> to inspect the values.
To try the steps first, run the reference app. Its generator runs at 20 Hz, so the rate on its published topic should be about 20 Hz:
On exit the reference app logs the poses sent, relayed and received. The three counts should match, and the app exits non-zero if no pose completed the round trip.
If the bridge was built with the CUDA buffer backend and the machine has a CUDA device, the app also round-trips a 640x480 image through ROS 2 as a CUDA buffer, and logs the image counts too. Otherwise it warns that the GPU image path is skipped and runs the pose round trip alone. If the backend plugin is missing from the process, the relay receives the image in host memory and the app fails and says so.
📄 Example output with the GPU image path
With a 10-second run. Log prefixes and ROS middleware messages are omitted:
Publish one output on several topics
Call to_ros2 once per topic with the same output and a different port_name:
Match a node’s QoS
Set qos on the topic spec to match the ROS 2 node. A reliable subscription does not match a
best-effort publisher, which is typical of camera drivers, and the topic stays silent. For such a
publisher, use rclcpp::SensorDataQoS():
Receive camera images
The default converter converts between sensor_msgs/msg/Image and holoscan::schema::ImageT. The
pixels can stay in host memory, which is the default (memory_kind = kHost), or in GPU memory.
In host memory
The default size bound is 8 MiB, which covers a 1080p rgb8 frame. For larger frames, set
max_tensor_bytes to width × height × bytes per pixel. For a 4K rgb8 frame:
publisher_memory says what the ROS publisher sends. A host topic works without it, but setting it
to kHost states that the publisher sends host memory, and keeps the topic correct if you later
move it to GPU memory.
In GPU memory
A GPU ROS publisher can feed GPU operators with no copy through host memory. This needs the CUDA
buffer backend in your build and in every ROS process involved. Set memory_kind to
kCudaDevice. The bridge puts all of its device topics on one GPU, which you choose with
pool_device when you construct it:
The SDK does not guess a CUDA device, so bind the imported topic to the bridge’s GPU and pass the
options to compile():
If a ROS node in the same process as the bridge publishes or subscribes these GPU images, turn on intra-process communication for both the bridge and that node, as the reference app does. The images are then handed over in place. Nodes in other processes need nothing:
Other combinations are possible, such as a host publisher feeding a GPU topic, or publishing a GPU
tensor with to_ros2.
See the library README for each case.
Sample a ROS 2 input by time
If an operator reads a from_ros2 port with LatestWithin, Exact, DrainAll, OnAligned or
BracketedWindow, each message needs a capture time. Set capture_time_clock to the graph clock.
The bridge uses each message’s header.stamp as its capture time.
The clock must count the same time as the ROS 2 stamps. For wall-clock ROS 2, that is
use_time_since_epoch = true, as above. A message type with no header, such as Pose, is stamped
with the time the bridge received it, and the bridge logs a warning. Triggers that fire on arrival,
such as OnEach, do not need a capture time.
Use your own message type
Register a converter for the pair, extend the built-in set, and pass it to the bridge:
The Converter specialization itself is described in the
library README.
If the topic is not what you expect
⚠️ compile() fails with EXTERNAL_CHANNEL_PLAN_INVALID
A from_ros2 port is wired to more than one operator. Wire it to one.
⚠️ The first messages are missing
Messages published before ROS 2 discovery matches the publisher and subscriber can be dropped,
which is normal for a stream. If you need the first message, wait about 200 ms between
start() and run_async(), as the reference app does.
⚠️ A topic stays silent and rclcpp warns about incompatible QoS
The publisher and subscriber QoS do not match. Set qos on the topic spec to match the ROS 2
node. See Match a node’s QoS.
⚠️ compile() fails with IMPLICIT_DEVICE_ZERO_REJECTED
A GPU topic has no device binding. Bind the imported topic, or the operator that produces an
exported topic’s tensor, in the options you pass to compile(). See
In GPU memory.
⚠️ A from_ros2 or to_ros2 call does not compile
The <Ros2T, HsdkT> pair is not registered. See
Use your own message type.
⚠️ compile() fails with TEMPORAL_CAPTURE_TIME_REQUIRED
An operator reads a from_ros2 port with an event-time selector, and the port has no capture time.
Set capture_time_clock on that port’s topic spec. See
Sample a ROS 2 input by time.
⚠️ LatestWithin never selects a message
The graph clock and the ROS 2 stamps do not count the same time, usually because the graph uses a
default RealtimeClock, which counts from its own start. Create it with
use_time_since_epoch = true. See Sample a ROS 2 input by time.
Related
-
Library README: built-in message pairs, converter contracts, tensor messages, capture time and wiring limits.
-
ROS 2 bridge reference: the runnable app and its run options.