Version: Next

ROS Cheat Sheet

note

This page is intended to provide quick reference to common ROS commands and concepts. It is not an exhaustive resource.

Please refer to the official ROS docs for complete documentation.

note

In any bash command, items contained within square brackets ([]) means the items with the brackets are optional, and may be omitted.

ROS command-line tools

Since ROS 2 launched, all ROS 2 terminal commands are of the format ros2 command [verb] [args...]

Setting the `ROS_DOMAIN_ID`

Because of its distributed nature, ROS 2 uses numbered domains to manage communication between nodes. Before running any ros2 commands, make sure your domain is set correctly.

export ROS_DOMAIN_ID=0

Domain IDs can be any integer from 0 to 232, though general convention is to avoid using any domain ID higher than 100 unless absolutely necessary.

If unset, the default domain ID is 0.

Interacting with nodes

Start a node

ros2 run package_name executable_name [args] [--ros-args [-r original_topic:=remapped_topic] [-p parameter_name:=parameter_value]]

Start multiple nodes with a launch file

ros2 launch [--debug] package_name launch_file.launch.py [launch arguments...]

List running nodes

ros2 node list

Inspect a node

ros2 node info /fully/qualified/node_name

Interacting with topics

List published topics

ros2 topic list

Inspect a topic

ros2 topic info /fully/qualified/topic_name [--verbose]

Echo a topic

ros2 topic echo /fully/qualified/topic_name

Check the publish rate of a topic

ros2 topic hz /fully/qualified/topic_name

Publish a topic

ros2 topic pub /fully/qualified/topic_name package/msg/Type '{ JSON-formatted message payload goes here }' [-r HZ]

where HZ is the desired frequencey of the publication in Hz. The contents of the JSON-formatted payload depends on the type of message being published. Below are some concrete examples:

ros2 topic pub /hello_world std_msgs/msg/String '{"data": "Hello World"}' -r 0.5

ros2 topic pub /a200_0000/cmd_vel geometry_msgs/msg/Twist '{"linear": {"x": 0.5}}` -r 10

Interacting with services

List services

ros2 service list

Inspect a service

ros service info /fully/qualified/service_name

Call a service

ros2 service call /fully/qualified/service_name package/srv/Type ['{ JSON-formatted service args here }']

Interacting with actions

List actions

ros2 actions list

Inspect an action

ros2 action info /fully/qualified/action_name

Sending a goal to an action

ros actions info /fully/qualified/action_name ['{ JSON-formatted action goal }']

Restart the ROS 2 daemon

Running any ros2 command will automatically start the daemon if it isn't running already.

You can stop the daemon by running

ros2 daemon stop

The daemon will automatically restart the next time you run a ros2 command.

Workspaces

A ROS workspace is a directory with a specific structure used to build ROS packages from source.

Workspaces can have any name and be located anywhere on your local filesystem. For simplity this document uses colcon_ws as the name of the workspace directory.

Creating a workspace

mkdir -p colcon_ws/src
cd colcon_ws
colcon build
source install/setup.bash

Add a source package to the workspace

cd /path/to/colcon_ws/src
git clone https://github.com/org/repo_name.git -b repo_branch

Resolve dependencies within a workspace

note

Make sure you've already run sudo rosdep init once on your system to initialize rosdep the first time!

cd /path/to/colcon_ws/
rosdep update
rosdep install --from-paths src --ignore-src -r -y

Packages

Create a package

CMake package:

cd /path/to/colcon_ws/src
ros2 pkg create --build-type ament_cmake [--license your_license] package_name

Python package:

cd /path/to/colcon_ws/src
ros2 pkg create --build-type ament_python [--license your_license] package_name

Supported licenses include:

Apache-2.0
BSL-1.0
BSD-2.0
BSD-2-Clause
BSD-3-Clause
GPL-3.0-only
LGPL-3.0-only
MIT
MIT-0

Package files and folders

File Path	Description
`package.xml`	ROS package information
`CMakeLists.txt`	CMake package build instructions
`setup.cfg`	Python `setuptools` configuration
`setup.py`	Python package build instructions

Directory path	Description
`package_name/`	Python3 source files
`include/package_name/`	C++ header files
`src/`	C++ source files
`action/`, 'msg/`, 'srv/`	ROS action, message, and service definitions

Releasing packages

cd /path/to/colcon_ws/src/repository_name
catkin_generate_changelog
# review & edit changelogs as necessary
git add .
git commit -m "Changes"
catkin_prepare_release [--bump major|minor|patch]
bloom-release -t $ROS_DISTRO -r $ROS_DISTRO repository_name

`package.xml`

Skeleton

CMake package:

<?xml version="1.0"?>
<?xml-model
   href="http://download.ros.org/schema/package_format3.xsd"
   schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
  <name>package_name</name>
  <version>0.0.0</version>
  <description>Package description</description>
  <maintainer email="my_email@my_provider.domain">Maintainer's Name</maintainer>
  <license>your_license</license>

  <buildtool_depend>ament_cmake</buildtool_depend>

  <test_depend>ament_lint_auto</test_depend>
  <test_depend>ament_lint_common</test_depend>

  <!--
    Add dependencies here
  -->

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

Python package:

<?xml version="1.0"?>
<?xml-model
   href="http://download.ros.org/schema/package_format3.xsd"
   schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
  <name>package_name</name>
  <version>0.0.0</version>
  <description>Package description</description>
  <maintainer email="my_email@my_provider.domain">Maintainer's Name</maintainer>
  <license>your_license</license>

  <test_depend>ament_copyright</test_depend>
  <test_depend>ament_flake8</test_depend>
  <test_depend>ament_pep257</test_depend>
  <test_depend>python3-pytest</test_depend>

  <!--
    Add dependencies here
  -->

  <export>
    <build_type>ament_python</build_type>
  </export>
</package>

`CMakeLists.txt`

Skeleton

cmake_minimum_required(VERSION 3.8)
project(package_name)
find_package(ament_cmake REQUIRED)
ament_package()

Actions, messages, and services

Add all of your .action, .msg, and .srv files to CMakeLists.txt:

rosidl_generate_interfaces(
    ${PROJECT_NAME}
        action/my_action.action
        msg/my_message.msg
        srv/my_service.srv
)

If your definitions contain messages from other packages, add them as dependencies, e.g.:

rosidl_generate_interfaces(
    ${PROJECT_NAME}
        action/my_action.action
        msg/my_message.msg
        srv/my_service.srv
    DEPENDENCIES
        geometry_msgs
        std_msgs
)

Add the following to package.xml:

<buildtool_depend>rosidl_default_generators</buildtool_depend>
<exec_depend>rosidl_default_runtime</exec_depend>
<member_of_group>rosidl_interface_packages</member_of_group>

<!-- plus any external packages you depend on, e.g. -->
<depend>geometry_msgs</depend>
<depend>std_msgs</depend>

Build libraries and executables

Each package can contain multiple executables or libraries

add_executable(my_executable src/my_executable_source.cpp)

add_library(my_library src/my_library_source.cpp)

If your executables or libraries require additional dependencies you must add them too:

find_package(dependency_1 REQUIRED)
find_package(dependency_2 REQUIRED)

add_executable(my_executable src/my_executable_source.cpp)
ament_target_dependencies(my_executable dependency_1)

add_library(my_library src/my_library_source.cpp)
ament_target_dependencies(my_library dependency_2)

Installation

To install C++ executables add the following to CMakeLists.txt:

install(
  PROGRAMS
    my_executable

  DESTINATION
    lib/${PROJECT_NAME}
)

To install C++ libraries, add the following to CMakeLists.txt:

install(
  TARGETS
    my_library

  LIBRARY DESTINATION lib
  RUNTIME DESTINATION lib/${PROJECT_NAME}
)

To add configuration, launch, and other directories, add the following to CMakeLists.txt:

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

`setup.py`

note

This file repeats some information found in package.xml; the information in both files must match!

Skeleton

from setuptools import find_packages, setup

package_name = 'package_name'

setup(
    name=package_name,
    version='0.0.0',
    packages=find_packages(exclude=['test']),
    data_files=[
        ('share/ament_index/resource_index/packages',
            ['resource/' + package_name]),
        ('share/' + package_name, ['package.xml']),
    ],
    install_requires=['setuptools'],
    zip_safe=True,
    maintainer='Maintainer Name',
    maintainer_email='my_email@my_provider.domain',
    description='Package description',
    license='your_license',
    tests_require=['pytest'],
    entry_points={
        'console_scripts': [
        ],
    },
)

Installation

To add executables to your Python package, add them to the entry_points dict:

entry_points={
    'console_scripts': [
        'my_executable = my_executable.MyExecutableNode:main'
    ],
}

To install launch, config, and other directories or files, add them to the data_files array:

data_files = [
    ('share/ament_index/resource_index/packages',
        ['resource/' + package_name]),
    ('share/' + package_name, ['package.xml']),
    (os.path.join('share', package_name, 'config'), glob(
        os.path.join('config', '*.yaml'))),
    (os.path.join('share', package_name, 'launch'), glob(
        os.path.join('launch', '*.launch.py'))),
]

`setup.cfg`

Skeleton

[develop]
script_dir=$base/lib/package_name
[install]
install_scripts=$base/lib/package_name

ROS command-line tools​

Setting the ROS_DOMAIN_ID​

Interacting with nodes​

Start a node​

Start multiple nodes with a launch file​

List running nodes​

Inspect a node​

Interacting with topics​

List published topics​

Inspect a topic​

Echo a topic​

Check the publish rate of a topic​

Publish a topic​

Interacting with services​

List services​

Inspect a service​

Call a service​

Interacting with actions​

List actions​

Inspect an action​

Sending a goal to an action​

Restart the ROS 2 daemon​

Workspaces​

Creating a workspace​

Add a source package to the workspace​

Resolve dependencies within a workspace​

Packages​

Create a package​

Package files and folders​

Releasing packages​

package.xml​

Skeleton​

CMakeLists.txt​

Skeleton​

Actions, messages, and services​

Build libraries and executables​

Installation​

setup.py​

Skeleton​

Installation​

setup.cfg​

Skeleton​

ROS command-line tools

Setting the `ROS_DOMAIN_ID`

Interacting with nodes

Start a node

Start multiple nodes with a launch file

List running nodes

Inspect a node

Interacting with topics

List published topics

Inspect a topic

Echo a topic

Check the publish rate of a topic

Publish a topic

Interacting with services

List services

Inspect a service

Call a service

Interacting with actions

List actions

Inspect an action

Sending a goal to an action

Restart the ROS 2 daemon

Workspaces

Creating a workspace

Add a source package to the workspace

Resolve dependencies within a workspace

Packages

Create a package

Package files and folders

Releasing packages

`package.xml`

Skeleton

`CMakeLists.txt`

Skeleton

Actions, messages, and services

Build libraries and executables

Installation

`setup.py`

Skeleton

Installation

`setup.cfg`

Skeleton