ROS 2 has three main ways nodes (i.e. the individual C++ or Python programs that make up the robotics system you’re building) can communicate with each other.

• Topics
• Services
• Actions

Below I will detail the circumstances when you should use each of these communication methods.

Use Topics for Continuous Data Streams

Use topics when you have continuous data streams (e.g. sensor data, robot state, etc.). 

An example of a continuous data stream is laser scan data generated by LIDAR. Data will be continuously published on the topic as long as the robot is up and running.

The data types used in topic-based communication are known as messages. Nodes publish messages via topics, and nodes subscribe to messages via topics.

You can use standard ROS 2 message data types, or you can create your own custom message data types.

Use Services for Quick Request/Response Communication

Services should be used for fast request/response communication. A Service Client node sends a request (typically for some data) to a Service Server node. The Service Server node then replies to that request with a response.

An example of a service is in this post where I call a service to load a new map once a robot has reached a new floor of a building.

Use Actions for Long-Running Tasks That Have a Clear Beginning and End

Actions should be used for long running processes that have a clear beginning and end. An action is made up of a goal, interim feedback (to keep you updated on the progress being made to reach the goal), and a result.

An Action Client node sends a request (i.e. a Goal) to an ActionServer. The goal might be, for example, for the robot to move to a particular location in the environment.

The Action Server node gives the Action Client feedback on the progress it is making towards the execution of that goal (e.g. the robot’s most recent position along the path towards the goal location).

When the Action Server completes the goal, it sends a result message to the ActionClient.

That’s it! Keep building!

In a ROS 2 project, code is organized into packages. A package is just a directory that contains files and folders. Each package might contain a mixture of code (e.g. ROS 2 nodes), data, libraries, images, documentation, etc. Every program you write in ROS 2 will need to be inside a package.

Suppose we have a ROS 2 package named my_robot_package. The file tree below shows a possible structure for a ROS 2 package. This structure is aligned with best practice for a ROS 2 package. I made a few tweaks (e.g. added rviz and maps folders). Note: You do not need to create all these folders in every ROS 2 package.

my_robot_package/

├── README (Describes the package*. Example)

├── CHANGELOG.rst (REP-0132 compliant changelog. Example.)

├── CONTRIBUTING (Describes the contribution guidelines. Example.)

├── LICENSE (A copy of the license or licenses for this package. Usually Apache 2.0. Example.)

├── setup.py (Where to install the Python modules. Python-only packages. Example.)

├── CMakeLists.txt (How to build the code and where to install. Packages with C++ code. Example.)

├── package.xml (Defines the package properties as defined by this convention. Example.)

├── action (Holds custom action definitions. Example.)

├── config (Holds configuration files … i.e. yaml. Example.)

├── doc (Holds all the documentation. Example.)

├── launch (Holds launch files. Example.)

├── maps (Holds map files. Example.)

├── models (Holds SDF model files. Example.)

├── msg (Holds custom message definitions. Example.)

├── rviz (Holds RViz configuration files. Example.)

├── srv (Holds custom service definitions. Example.)

├── test (All system (btw packages), integration (btw code), and/or unit (w/n code) test data. Example.)

├── urdf (Contains URDF files. Example.)

├── worlds (Contains Gazebo world files. Example.)

├── my_robot_package (Holds Python files that can be imported into other Python files. Example.)

│     ├── __init__.py

│     └── python_module_to_import.py

├── scripts (Holds Python code.**. Example.)

│     └── py_node.py

├── include (Holds C++ header files and libraries we want to use inside this package. Example.)

│     └── my_robot_package

│               └── cpp_header.hpp

└── src (Holds C++ source code.***. Example.)

        └── cpp_node.cpp

* All packages should have these documentation elements present in their README or linked to from their README:

• Description and purpose
• Definition and description of the public API
• Examples
• How to build and install (should reference external tools/workflows)
• How to build and run tests
• How to build documentation
• How to develop (useful for describing things like python setup.py develop)
• License and copyright statements

** Check this page for best practices on code style and language versions for C++, Python, and README files.

*** Each source file must have a license and copyright statement, checked with an automated linter.

In this tutorial, I discuss the best practices for naming and organizing packages in ROS 2 projects. 

You can find the official best practices on this page. I will elaborate on the most important best practices below, as well as add some best practices that the official guide left out.

Use a Prefix for Robot-Specific Functionality

Add the prefix “my_robot_” for packages that are specifically designed for your robot (credit to RoboticsBackend.com for this one).

Use a Suffix to Describe the Purpose of a Package

To the end of a package name, add a word that is specific enough to describe what the package does (e.g. my_robot_navigation).

Package Names Should Be In Lowercase

Package names should follow common C variable naming conventions: lower case, start with a letter, use underscore separators, e.g. my_robot_navigation.

Make It Easy to Maintain

You should be able to make changes in one package without breaking other packages.

One Package, One Purpose

Each package should have only one purpose.

Minimize Dependencies

Each package should only use the dependencies that it needs.

Example ROS 2 Project Package Architecture

For example, consider the following packages that might reside in a folder named ~/ros2_ws/src/my_robot :

• my_robot
• my_robot_base
• my_robot_bringup 
• my_robot_description
• my_robot_gazebo
• my_robot_kinematics
• my_robot_localization
• my_robot_manipulation
• my_robot_moveit_config
• my_robot_msgs 
• my_robot_navigation
• my_robot_teleop
• my_robot_tests
• my_robot_rviz_plugins

Let’s write the purpose for each package below:

• my_robot (This package is a metapackage. A metapackage doesn’t contain anything except a list of dependencies to other packages. You can use a metapackage to make it easier to install multiple related packages at once. Package installation tools like apt-get can automatically install all the ROS2 packages on which a metapackage directly or indirectly depends. Example.).
• my_robot_base (This package is used to control the motors of your robot. Example.)
• my_robot_bringup (Put the ROS 2 launch files that bring up the robot inside this folder. Example.)
• my_robot_description (Contains the URDF and mesh files of your robot. Example.)
• my_robot_gazebo (Configuration and launch files for spawning the robot in Gazebo. Example)
• my_robot_kinematics (Your forward and inverse kinematics algorithms go here. Example.)
• my_robot_localization (Files for localizing in an environment. Example.)
• my_robot_manipulation (Contains algorithms for manipulating objects in the environment. Example.)
• my_robot_moveit_config (Configuration files using the MoveIt framework. Example.)
• my_robot_msgs (Contains custom messages, services, and actions. Example.)
• my_robot_navigation (Contains configuration and launch files for the ROS 2 Navigation Stack. Example.)
• my_robot_teleop (A node for manually tele-operating a robot using a keyboard, joystick, game console controller, etc. Example.)
• my_robot_tests (A package used for system tests. Example.)
• my_robot_rviz_plugins (RViz specific plugins go here. Example.)

That’s it. Keep building!