ROS 2 CLI & Architectural Field Guide

ROS 2 Command Reference & Cheat Sheet

Production-ready reference for ROS 2 Humble & Jazzy: interactive CLI explorer, QoS compatibility matrix, DDS network discovery config, CMake/Python package boilerplate, and common runtime error resolutions.

⚡ Interactive CLI Command Explorer

Search 40+ vital ROS 2 commands by keyword or filter by subsystem.

List active topics with types Topic

ros2 topic list -t

Prints all published and subscribed topics along with their message type interface.

Echo topic data in real-time Topic

ros2 topic echo /cmd_vel

Streams live published messages to stdout in human-readable YAML representation.

Measure publication frequency Topic

ros2 topic hz /scan

Computes real-time publishing rate in Hertz (average, min, max, std dev).

Measure topic bandwidth Topic

ros2 topic bw /camera/image_raw

Displays bandwidth consumption (KB/s or MB/s) and message payload sizes.

Publish message from CLI Topic

ros2 topic pub --rate 10 /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.5}, angular: {z: 0.2}}"

Publishes structured YAML messages continuously at 10 Hz or once via -1.

Inspect topic QoS & endpoints Topic

ros2 topic info -v /odom

Lists endpoint count and detailed Quality of Service profiles for publishers/subscribers.

List all active nodes Node

ros2 node list

Prints the full namespace and names of all discovered nodes in the ROS domain.

Node topology & interfaces Node

ros2 node info /diff_drive_controller

Displays all topics subscribed/published, services provided/called, and action servers.

List all services Service

ros2 service list -t

Lists all active ROS 2 service servers along with their request/response types.

Call a service with arguments Service

ros2 service call /spawn turtlesim/srv/Spawn "{x: 2.0, y: 2.0, theta: 0.0, name: 'turtle2'}"

Synchronously sends a service request and waits for the server response.

List active actions Action

ros2 action list -t

Lists all action servers providing goal, feedback, and result lifecycle management.

Send action goal with feedback Action

ros2 action send_goal --feedback /navigate_to_pose nav2_msgs/action/NavigateToPose "{pose: {pose: {position: {x: 1.0, y: 2.0}}}}"

Sends an action goal and prints continuous intermediate feedback until completion.

Dump node parameters to YAML Param

ros2 param dump /controller_manager > params.yaml

Exports the current live configuration parameters of a node into a reusable YAML file.

Set parameter value dynamically Param

ros2 param set /robot_state_publisher publish_frequency 50.0

Updates a node parameter at runtime without stopping or rebuilding the process.

Record topics with MCAP storage Bag

ros2 bag record -s mcap -o my_recording /tf /tf_static /scan /odom

Records high-performance robotic telemetry into modern zero-copy MCAP format.

Play recorded bag with sim time Bag

ros2 bag play --clock 100 my_recording/

Replays messages and publishes /clock at 100 Hz for synchronized simulation.

Launch robot system Launch

ros2 launch my_robot_bringup robot.launch.py use_sim_time:=true

Executes complex multi-node orchestrations with customizable command-line arguments.

Create new ROS 2 package Pkg

ros2 pkg create --build-type ament_cmake --dependencies rclcpp std_msgs sensor_msgs my_pkg

Scaffolds an ament_cmake or ament_python package with auto-configured manifests.

🛡️ Quality of Service (QoS) Compatibility Matrix

In ROS 2, publishers and subscribers must have compatible QoS policies to communicate. If policies clash, connections silently fail or throw endpoint warnings.

Policy	Publisher Setting	Subscriber Setting	Compatibility	Typical Robotic Use Case
Reliability	Reliable	Reliable	✓ Compatible	Control commands, mission status, goal points
Reliability	Reliable	Best Effort	✓ Compatible	Subscriber allows drops; Publisher delivers all
Reliability	Best Effort	Reliable	✗ INCOMPATIBLE	Subscriber demands ACK; Publisher won't provide
Reliability	Best Effort	Best Effort	✓ Compatible	High-bandwidth sensors (LiDAR scans, camera feeds)
Durability	Transient Local	Transient Local	✓ Compatible	Latched data (Static map, robot description URDF)
Durability	Transient Local	Volatile	✓ Compatible	Late-joining subscriber only wants future data
Durability	Volatile	Transient Local	✗ INCOMPATIBLE	Subscriber expects cached history; Publisher discards
Durability	Volatile	Volatile	✓ Compatible	High-rate volatile state (Wheel odometry, IMU)

Rule of Thumb: Offered must be ≥ Requested. A publisher can offer higher guarantees (Reliable, Transient Local) than a subscriber requests, but a subscriber cannot demand more guarantees than the publisher offers.

🌐 DDS Network Discovery & Domain Isolation

ROS 2 uses Data Distribution Service (DDS) as its underlying middleware (e.g. CycloneDDS, FastDDS). Configure these environment variables for multi-robot swarms, Wi-Fi stability, and subnet isolation.

ROS_DOMAIN_ID Isolation

Prevents crosstalk between multiple robots or developers sharing the same local Wi-Fi / Ethernet LAN (valid IDs: 0 to 101).

            export ROS_DOMAIN_ID=42
echo "export ROS_DOMAIN_ID=42" >> ~/.bashrc
          

Localhost Only (Zero LAN Leakage)

Forces all DDS multicast discovery to loopback 127.0.0.1. Essential for secure simulation and lab testing.

export ROS_LOCALHOST_ONLY=1

Select DDS RMW Implementation

Switch between Eclipse CycloneDDS (industry standard for robotics) and eProsima FastDDS.

export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

Custom CycloneDDS Configuration (Unicast over Wi-Fi)

Wi-Fi routers frequently drop UDP multicast discovery packets. Save this as cyclonedds.xml to enable reliable unicast peering:

<CycloneDDS xmlns="https://cdds.io/config">
  <Domain id="any">
    <General>
      <NetworkInterfaceAddress>wlan0</NetworkInterfaceAddress>
      <AllowMulticast>false</AllowMulticast>
    </General>
    <Discovery>
      <Peers>
        <Peer address="192.168.1.100"/> <!-- Robot SBC IP -->
        <Peer address="192.168.1.101"/> <!-- Workstation IP -->
      </Peers>
    </Discovery>
  </Domain>
</CycloneDDS>

export CYCLONEDDS_URI=file:///path/to/cyclonedds.xml

📦 Package Manifest & Build Boilerplate

C++ (CMakeLists.txt) Standard Template

cmake_minimum_required(VERSION 3.8)
project(my_robot_controller)

if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
  add_compile_options(-Wall -Wextra -Wpedantic)
endif()

find_package(ament_cmake REQUIRED)
find_package(rclcpp REQUIRED)
find_package(geometry_msgs REQUIRED)
find_package(sensor_msgs REQUIRED)

add_executable(motor_node src/motor_node.cpp)
ament_target_dependencies(motor_node rclcpp geometry_msgs sensor_msgs)

install(TARGETS
  motor_node
  DESTINATION lib/${PROJECT_NAME}
)

install(DIRECTORY launch config
  DESTINATION share/${PROJECT_NAME}
)

ament_package()

Python (setup.py) Standard Template

from setuptools import find_packages, setup
import os
from glob import glob

package_name = 'my_py_controller'

setup(
    name=package_name,
    version='0.1.0',
    packages=find_packages(exclude=['test']),
    data_files=[
        ('share/ament_index/resource_index/packages', ['resource/' + package_name]),
        ('share/' + package_name, ['package.xml']),
        (os.path.join('share', package_name, 'launch'), glob('launch/*.launch.py')),
        (os.path.join('share', package_name, 'config'), glob('config/*.yaml')),
    ],
    install_requires=['setuptools'],
    zip_safe=True,
    maintainer='Robotics Engineer',
    maintainer_email='engineer@robotics.pakspeaks.com',
    description='Python motor controller node',
    license='Apache-2.0',
    entry_points={
        'console_scripts': [
            'motor_node = my_py_controller.motor_node:main',
        ],
    },
)

🔧 Common ROS 2 Errors & Instant Fixes

Error Signature	Root Cause	Fix & Resolution
`Package 'xyz' not found`	Workspace overlay has not been sourced in the current terminal shell.	Run `source install/setup.bash` in your workspace root.
`rcl_interfaces/QoSCompatibilityWarning: Some topics were not compatible`	Mismatched QoS durability or reliability between publisher and subscriber.	Inspect with `ros2 topic info -v /topic` and match subscriber QoS (use `best_effort()` or `transient_local()`).
`RCL_RET_ALREADY_INITIALIZED`	Attempting to invoke `rclcpp::init()` or `rclpy.init()` twice in the same process.	Check if `rclpy.ok()` before calling init, or ensure multi-threaded executor uses a single context.
`LookupException: "base_link" passed to lookupTransform does not exist`	TF tree is broken or `robot_state_publisher` / static transforms are not broadcasting.	Run `ros2 run tf2_tools view_frames` to generate `frames.pdf` and verify transform roots.
Nodes cannot discover each other across two computers	Different `ROS_DOMAIN_ID`, Wi-Fi firewall blocking UDP multicast, or missing multicast routes.	Verify identical `export ROS_DOMAIN_ID=0`, disable `ufw` or open UDP ports 7400-7500, or switch to unicast `cyclonedds.xml`.