Imported from robotics-playground/skills (skills/ros2-dev/SKILL.md). Install upstream with npx skills add robotics-playground/skills --skill ros2-dev. Copyright stays with the author.

ROS 2 Development Companion

Quick navigation

• Node structures, callbacks, executors, lifecycle nodes --> references/node-patterns.md
• Topics, services, actions, QoS profiles, custom messages --> references/communication.md
• Workspace layout, colcon, ament, package creation --> references/workspace-build.md
• Launch files, arguments, composition, namespaces --> references/launch-files.md
• Coordinate frames, tf2, URDF, Xacro --> references/tf2-urdf.md
• CLI tools, rqt, RViz, DDS, logging, ros2 bag --> references/debugging.md
• Unit tests, integration tests, launch_testing, CI/CD --> references/testing.md
• Simulation debugging (Gazebo): odom-vs-physics, sim_time, drift --> references/simulation-debugging.md
• Ready-to-use diagnostic scripts (sim ground-truth comparison) --> scripts/

Core Philosophy: The ROS 2 Mindset

The fundamental paradigm shift in robotics is this: traditional software is request/response; robots are continuous data streams.

In a typical application, a client sends a request, a server processes it, and returns a response. The server is idle between requests. In robotics, sensors produce data continuously (30 Hz camera, 10 Hz LiDAR, 100 Hz IMU), processing nodes transform that data continuously, and actuator nodes consume commands continuously. There is no "idle."

Think of ROS 2 as a distributed event bus, not a request/response system.

The Three Laws of ROS 2 Development

1. Never block a callback. Callbacks run on executor threads. A blocked callback means missed messages. If you need to do slow work, use a separate thread or break the work into stages.

2. Never assume message delivery. Topics are lossy by default (best-effort QoS). Even with reliable QoS, network partitions happen. Design nodes to handle missing data gracefully.

3. Never use global state across callbacks. Each callback may run on a different thread (MultiThreadedExecutor). Use node-scoped state with proper synchronization.

Decision Table: Python vs C++ for This Node

ROS 2 supports both Python (rclpy) and C++ (rclcpp). For teams starting out, default to Python unless you have a specific reason for C++.

Recommendation: Write everything in Python first. Port individual nodes to C++ only when profiling shows Python is the bottleneck. ROS 2 is designed for mixed-language systems -- Python and C++ nodes communicate identically over topics/services/actions.

Decision Table: Which QoS Profile?

QoS (Quality of Service) controls message delivery guarantees. A mismatch between publisher and subscriber QoS causes silent failure -- no error, just no messages.

The #1 QoS Gotcha: If a publisher uses Best Effort and a subscriber uses Reliable, the subscriber will never receive messages. No error. No warning. Just silence. Always check QoS compatibility first when debugging "topic not showing up."

# Quick QoS profiles for common cases
from rclpy.qos import QoSProfile, ReliabilityPolicy, DurabilityPolicy, HistoryPolicy

SENSOR_QOS = QoSProfile(
    reliability=ReliabilityPolicy.BEST_EFFORT,
    durability=DurabilityPolicy.VOLATILE,
    history=HistoryPolicy.KEEP_LAST,
    depth=5
)

RELIABLE_QOS = QoSProfile(
    reliability=ReliabilityPolicy.RELIABLE,
    durability=DurabilityPolicy.VOLATILE,
    history=HistoryPolicy.KEEP_LAST,
    depth=10
)

LATCHED_QOS = QoSProfile(
    reliability=ReliabilityPolicy.RELIABLE,
    durability=DurabilityPolicy.TRANSIENT_LOCAL,
    history=HistoryPolicy.KEEP_LAST,
    depth=1
)

Decision Table: Which Executor Model?

Executors determine how callbacks are scheduled. Think of them as the event loop.

# Default: single-threaded (safe, simple)
rclpy.spin(node)

# Multi-threaded: when you need parallel callback execution
from rclpy.executors import MultiThreadedExecutor
executor = MultiThreadedExecutor(num_threads=4)
executor.add_node(node)
executor.spin()

With MultiThreadedExecutor, you MUST use callback groups to control which callbacks can run in parallel. See references/node-patterns.md for details.

Node Architecture Selection

Start with simple nodes. Move to lifecycle nodes when you need deterministic startup ordering (e.g., "configure the camera before the detector starts"). Move to component nodes when profiling shows IPC overhead matters.

See references/node-patterns.md for implementation patterns for each type.

Anti-Patterns Table

These are the most common mistakes made by developers new to ROS 2.

Common Beginner Error Diagnosis

Coding Conventions Summary

See individual reference files for full details. Key rules for this team:

Python (rclpy) -- Primary Language

• Node names: snake_case -- e.g., lidar_processor, camera_driver
• Topic names: snake_case with namespace -- e.g., /robot/cmd_vel, /sensors/imu/data
• Package names: snake_case -- e.g., my_robot_perception
• File names: snake_case.py -- e.g., lidar_processor_node.py
• Class names: PascalCase -- e.g., LidarProcessorNode
• Callbacks: _callback suffix -- e.g., image_callback, timer_callback
• Parameters: Declare all in __init__ with defaults and descriptions
• Logging: Use self.get_logger().info(), never print()

C++ (rclcpp) -- For Performance-Critical Nodes

• Follow the same naming for nodes, topics, packages
• Files: snake_case.cpp / snake_case.hpp
• Classes: PascalCase
• Functions/methods: snake_case
• Member variables: trailing_underscore_

General ROS 2 Conventions

• Follow REP 103 for units (SI) and coordinate frames (x-forward, y-left, z-up)
• Follow REP 105 for standard frame names (map, odom, base_link)
• Follow standard ROS 2 naming conventions for topics (lowercase, namespaced)
• Use existing message types from std_msgs, sensor_msgs, geometry_msgs, nav_msgs before creating custom messages
• Prefix custom message packages with your project name -- e.g., my_robot_msgs

Package Organization Example

Recommended package structure for an inspection robot:

my_robot_ws/
  src/
    my_robot_bringup/       # Launch files, configs, system startup
    my_robot_description/   # URDF/Xacro, meshes, robot model
    my_robot_msgs/          # Custom message/service/action definitions
    my_robot_perception/    # Camera, LiDAR processing nodes
    my_robot_navigation/    # Path planning, obstacle avoidance
    my_robot_control/       # Motor control, velocity commands
    my_robot_detection/     # Object/defect detection, analysis
    my_robot_teleop/        # Manual control interface
    my_robot_simulation/    # Gazebo worlds, sim-specific launch

Each package should have a single, clear responsibility. Packages communicate only through ROS 2 interfaces (topics, services, actions) -- never by importing each other's Python modules directly.

Message Type Selection Guide

Choosing the right message type is a common stumbling block. Use existing messages from standard packages before creating custom ones.

When to create a custom message:

• None of the standard types fit your data
• You need domain-specific fields (e.g., PipeDefect with defect_type, confidence)
• You need to bundle multiple pieces of related data

When NOT to create a custom message:

• A standard type almost works -- use it and ignore unused fields
• You just need a label on data -- use the Header.frame_id field
• You just need a simple value -- use std_msgs

ROS 2 Jazzy Environment Setup

Prerequisites (Ubuntu 24.04)

# Set locale
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

# Add ROS 2 apt repository
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
  -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \
  http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | \
  sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# Install ROS 2 Jazzy
sudo apt update
sudo apt install ros-jazzy-desktop  # Full desktop (recommended)
# or: sudo apt install ros-jazzy-ros-base  # Minimal (headless robots)

# Install development tools
sudo apt install python3-colcon-common-extensions python3-rosdep python3-vcstool

# Initialize rosdep
sudo rosdep init
rosdep update

# Source ROS 2 in every terminal
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc

Verify Installation

# Check ROS 2 is working
echo $ROS_DISTRO
ros2 doctor

# Run a demo
ros2 run demo_nodes_cpp talker &
ros2 run demo_nodes_py listener
# You should see "I heard: [Hello World: N]"

Recommended DDS Configuration

For a small team on a local network, Cyclone DDS is simpler and more reliable than the default Fast-DDS:

sudo apt install ros-jazzy-rmw-cyclonedds-cpp
echo "export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp" >> ~/.bashrc
source ~/.bashrc

Naming Convention Quick Reference

Consistent naming prevents the most common class of bugs (silent connection failures due to typos).

Common ROS 2 CLI Commands Reference

Emergency Cheat Sheet

When things go wrong, run these commands in order:

# 1. Is ROS 2 working at all?
ros2 doctor --report

# 2. What nodes are running?
ros2 node list

# 3. What topics exist?
ros2 topic list -t    # -t shows message types

# 4. Is data flowing on a topic?
ros2 topic hz /my_topic        # message rate
ros2 topic echo /my_topic      # actual data (add --qos-reliability best_effort if needed)

# 5. Can nodes see each other?
ros2 node info /my_node        # shows subscribers, publishers, services

# 6. Is tf2 working?
ros2 run tf2_tools view_frames  # generates frames.pdf

# 7. What's the QoS on a topic?
ros2 topic info /my_topic -v   # -v shows QoS details

# 8. Nuclear option: restart DDS discovery
export ROS_LOCALHOST_ONLY=1    # restrict to localhost
# or kill and restart the daemon:
ros2 daemon stop && ros2 daemon start

Reference File Index