Skip to content

elliewlh2094/codex-robotics-skills / .agents/skills/ros2-messaging

ros2-messaging

Verified

ROS2 publisher, subscriber, QoS, custom message, synchronization, and zero-copy communication patterns. Use when designing topic graphs, choosing QoSProfile policies, debugging topics that connect but deliver no data, defining msg interfaces or interface packages, using rosidl_generate_interfaces, message_filters, ApproximateTime, ExactTime, intra-process comms, rclcpp components, namespaces, remappings, or topic naming.

ROS2 Messaging

When to Use This Skill

  • Designing the topic graph for a robot or feature (what publishes what, with which QoS)
  • Choosing the right QoSProfile for sensors, commands, state, transforms, or maps
  • Debugging "publisher and subscriber both exist but nothing arrives" (almost always QoS)
  • Designing a custom .msg and standing up a _msgs interfaces package
  • Synchronizing two or more topics by timestamp (message_filters)
  • Cutting copy/serialization overhead with intra-process communication and UniquePtr
  • Naming topics consistently across a fleet

QoS: The #1 Source of "Topic Doesn't Connect" Bugs

A publisher and subscriber must have compatible QoS. Most "silent failure" bugs are QoS mismatches.

Publisher        Subscriber       Connect?
RELIABLE         RELIABLE         Yes
RELIABLE         BEST_EFFORT      Yes
BEST_EFFORT      BEST_EFFORT      Yes
BEST_EFFORT      RELIABLE         NO — silent failure (most common bug)

Durability matters too: a VOLATILE publisher will not deliver to a TRANSIENT_LOCAL subscriber that joined late.

Diagnose a QoS mismatch in 10 seconds

ros2 topic info /camera/image_raw -v
# Look at "Reliability" and "Durability" for both publishers and subscribers.
# If they don't match per the table above → that's your bug.

Recommended QoS Profiles

from rclpy.qos import (
    QoSProfile, QoSReliabilityPolicy as Rel, QoSHistoryPolicy as Hist,
    QoSDurabilityPolicy as Dur,
)

# Sensors (cameras, LiDAR, IMU): tolerate drops, want latest
SENSOR_QOS = QoSProfile(
    reliability=Rel.BEST_EFFORT,
    history=Hist.KEEP_LAST, depth=1,
    durability=Dur.VOLATILE,
)

# Commands (cmd_vel, joint goals): never miss
COMMAND_QOS = QoSProfile(
    reliability=Rel.RELIABLE,
    history=Hist.KEEP_LAST, depth=10,
    durability=Dur.VOLATILE,
)

# Maps, robot_description, static config: late joiners must receive
LATCHED_QOS = QoSProfile(
    reliability=Rel.RELIABLE,
    history=Hist.KEEP_LAST, depth=1,
    durability=Dur.TRANSIENT_LOCAL,   # the ROS2 replacement for ROS1 latching
)

# Default state/diagnostics
STATE_QOS = QoSProfile(
    reliability=Rel.RELIABLE,
    history=Hist.KEEP_LAST, depth=10,
)
#include <rclcpp/qos.hpp>

static const rclcpp::QoS SENSOR_QOS  = rclcpp::SensorDataQoS();
static const rclcpp::QoS COMMAND_QOS = rclcpp::QoS(10).reliable();
static const rclcpp::QoS LATCHED_QOS = rclcpp::QoS(1).reliable().transient_local();

Selection Guide

Data typeReliabilityDurabilityDepthExamples
Sensor (high freq)BEST_EFFORTVOLATILE1–5LiDAR, camera, IMU
CommandRELIABLEVOLATILE10cmd_vel, joint commands
State / configRELIABLETRANSIENT_LOCAL1robot_description, map
TransformsRELIABLEVOLATILE100/tf

Publisher / Subscriber Patterns

Python

class StatePublisher(Node):
    def __init__(self):
        super().__init__('state_publisher')
        self._pub = self.create_publisher(RobotState, 'robot/state', STATE_QOS)
        self.create_timer(0.1, self._tick)

    def _tick(self):
        msg = RobotState()
        msg.header.stamp = self.get_clock().now().to_msg()
        msg.battery_level = self._read_battery()
        self._pub.publish(msg)
class StateSubscriber(Node):
    def __init__(self, on_state):
        super().__init__('state_subscriber')
        self._on_state = on_state
        self.create_subscription(RobotState, 'robot/state',
                                 self._cb, STATE_QOS)
    def _cb(self, msg):
        self._on_state(msg)

C++

class StateSubscriber : public rclcpp::Node {
public:
  StateSubscriber() : Node("state_subscriber") {
    sub_ = create_subscription<robot_interfaces::msg::RobotState>(
        "robot/state", STATE_QOS,
        [this] (robot_interfaces::msg::RobotState::ConstSharedPtr msg) {
          on_state(*msg);
        });
  }
private:
  void on_state(const robot_interfaces::msg::RobotState& s) {
    // delegate to application logic; see ros2-clean-architecture
  }
  rclcpp::Subscription<robot_interfaces::msg::RobotState>::SharedPtr sub_;
};

Message Synchronization (message_filters)

When two topics describe the same instant (image + camera_info, left + right stereo), align them by timestamp.

import message_filters
from sensor_msgs.msg import Image, CameraInfo

def on_pair(image, info):
    process(image, info)

img_sub = message_filters.Subscriber(node, Image, 'image_raw')
info_sub = message_filters.Subscriber(node, CameraInfo, 'camera_info')

# ApproximateTime tolerates small clock skew between sources
sync = message_filters.ApproximateTimeSynchronizer(
    [img_sub, info_sub], queue_size=10, slop=0.05)
sync.registerCallback(on_pair)
#include <message_filters/subscriber.h>
#include <message_filters/sync_policies/approximate_time.h>
#include <message_filters/synchronizer.h>

using Image = sensor_msgs::msg::Image;
using Info  = sensor_msgs::msg::CameraInfo;

message_filters::Subscriber<Image> image_sub(node, "image_raw");
message_filters::Subscriber<Info>  info_sub(node, "camera_info");

using Policy = message_filters::sync_policies::ApproximateTime<Image, Info>;
auto sync = std::make_shared<message_filters::Synchronizer<Policy>>(
    Policy(10), image_sub, info_sub);
sync->registerCallback(
    [] (Image::ConstSharedPtr img, Info::ConstSharedPtr info) { ... });

Custom Messages: When and How

Reuse before you invent

Check common_interfaces first. The vast majority of topics map to existing types:

  • geometry_msgs/PoseStamped, Twist, Transform
  • sensor_msgs/Image, LaserScan, Imu, PointCloud2, JointState
  • nav_msgs/Odometry, Path, OccupancyGrid
  • std_msgs/Header (and only Header — see anti-pattern below)

Don't publish primitives

std_msgs/Float32, Bool, String, and example_interfaces/* are explicitly meant for prototyping and demos. In production, define a custom message that names the quantity:

# msgs/BatteryLevel.msg                    # GOOD — semantic meaning
std_msgs/Header header
float32 percentage      # 0.0 .. 100.0
float32 voltage         # volts
uint8 status
uint8 STATUS_OK = 0
uint8 STATUS_LOW = 1
uint8 STATUS_CRITICAL = 2
# Don't publish std_msgs/Float32 on /battery — the consumer can't tell what unit it is.

Enums via constants

ROS2 .msg files don't have native enums. Simulate with constants and a numeric field (see the STATUS_* lines above). This pattern is used throughout common_interfaces (e.g., diagnostic_msgs/DiagnosticStatus.level).

Custom _msgs package

Custom messages must live in their own package, suffixed _msgs. This decouples consumers from your implementation package.

robot_interfaces/
├── CMakeLists.txt
├── package.xml
├── msg/
│   ├── BatteryLevel.msg
│   └── RobotState.msg
├── srv/
│   └── SetMode.srv      # see ros2-service-action
└── action/
    └── NavigateToGoal.action
cmake_minimum_required(VERSION 3.8)
project(robot_interfaces)

find_package(ament_cmake REQUIRED)
find_package(rosidl_default_generators REQUIRED)
find_package(std_msgs REQUIRED)
find_package(geometry_msgs REQUIRED)
find_package(action_msgs REQUIRED)

rosidl_generate_interfaces(${PROJECT_NAME}
  "msg/BatteryLevel.msg"
  "msg/RobotState.msg"
  "srv/SetMode.srv"
  "action/NavigateToGoal.action"
  DEPENDENCIES std_msgs geometry_msgs action_msgs
)

ament_export_dependencies(rosidl_default_runtime)
ament_package()
<package format="3">
  <name>robot_interfaces</name>
  <version>0.1.0</version>
  <description>Robot interface definitions</description>
  <maintainer email="dev@example.com">Dev</maintainer>
  <license>Apache-2.0</license>

  <buildtool_depend>ament_cmake</buildtool_depend>
  <buildtool_depend>rosidl_default_generators</buildtool_depend>

  <depend>std_msgs</depend>
  <depend>geometry_msgs</depend>
  <depend>action_msgs</depend>

  <exec_depend>rosidl_default_runtime</exec_depend>
  <member_of_group>rosidl_interface_packages</member_of_group>

  <export><build_type>ament_cmake</build_type></export>
</package>

After building, source the install overlay before running consumer nodes — Python imports of generated message types fail if the overlay isn't sourced.

Topic Naming

Conventions that scale across a fleet:

RuleExample
Lowercase/robot/cmd_vel
Underscores for multi-word/joint_states
Avoid abbreviations/camera/image not /cam/img
Use namespaces/robot1/cmd_vel
Descriptive over short/laser_scan not /ls

Group by domain: /<robot>/<category>/<specific>

/robot/sensors/lidar/scan
/robot/sensors/camera/image_raw
/robot/control/cmd_vel
/robot/state/odometry
/robot/state/battery
/robot/perception/detections

Intra-Process Communication and Zero-Copy

For high-bandwidth data (images, point clouds) flowing between two nodes in the same process, intra-process comms (IPC) avoids serialization. With UniquePtr publish and a single subscriber, the message can be moved without copying.

#include <rclcpp_components/register_node_macro.hpp>

class PerceptionComponent : public rclcpp::Node {
public:
  explicit PerceptionComponent(const rclcpp::NodeOptions& opts)
      : Node("perception", opts) {  // opts come from container, may enable IPC
    rclcpp::SubscriptionOptions sub_opts;
    sub_opts.use_intra_process_comm = rclcpp::IntraProcessSetting::Enable;

    sub_ = create_subscription<sensor_msgs::msg::Image>(
        "image_raw", rclcpp::SensorDataQoS(),
        [this] (sensor_msgs::msg::Image::UniquePtr msg) {
          // UniquePtr → moved, not copied, when:
          //   • publisher also publishes UniquePtr
          //   • IPC is enabled in both
          //   • this is the only subscriber
          process(std::move(msg));
        },
        sub_opts);
  }
private:
  void process(sensor_msgs::msg::Image::UniquePtr msg);
  rclcpp::Subscription<sensor_msgs::msg::Image>::SharedPtr sub_;
};

RCLCPP_COMPONENTS_REGISTER_NODE(PerceptionComponent)

Run it inside a ComposableNodeContainer to share a process with its publisher (see ros2-launch-config).

Common Pitfalls

PitfallWhat goes wrongFix
BEST_EFFORT publisher, RELIABLE subscriberNo data delivered, no errorMatch QoS; use SensorDataQoS() on both ends for sensors
VOLATILE publisher of robot_descriptionLate-joining consumers (RViz, MoveIt) see nothingUse TRANSIENT_LOCAL durability
Publishing std_msgs/Float32 on /batteryConsumers can't infer units; brittle to refactorDefine BatteryLevel.msg with percentage, voltage, status
Custom messages in the same package as your nodesConsumers must depend on your whole package to use the messagePut messages in a separate _msgs package
Forgetting to source install/setup.bash after rebuilding msgsPython from my_msgs.msg import X failsRe-source the overlay; consider colcon build --symlink-install for Python
Subscribing twice with different QoSDuplicate processing or accidental dropPick one QoS per topic-direction; document it
ApproximateTimeSynchronizer with too-tight slopPairs never matchStart at 0.05–0.1s and tighten

Related Skills

  • ros2-node-creation — node skeletons that publish/subscribe
  • ros2-service-action — request/response and long-running tasks
  • ros2-launch-config — composing nodes for IPC, parameter files
  • ros2-transforms — /tf and /tf_static are messaging on geometry_msgs
  • ros2-bag — recording the topic graph for replay
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall