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!

Below are the attributes of high-quality ROS2-based systems.

Compatibility

Use standard ROS 2 message formats as much as possible to ensure the project is compatible with other ROS2-based systems.

Avoid using non-standard tools or libraries that may not be accessible to everyone.

Independence

Design ROS 2 nodes to be as hardware-independent as possible.

Extendibility

Make it easy to add new features and functionality.

Maintainability

Write and document code so that it is easy to make changes in the future.

Modularity

Divide nodes into small, independent, loosely coupled, highly cohesive, functional modules to avoid high technical debt. Each node should have a clear responsibility, and make sure nodes have minimal dependence on each other.

The easiest way to ensure modularity is to isolate what changes. Code that is likely to change in the future should be isolated from the rest of the system.

Performance

Software should be responsive and stable when run under its expected workload.

One technique for improving performance and reducing overhead at runtime is to not persist raw data if only a piece of it will be used. 

For example, if you have a robotic arm on a conveyor belt with an overhead camera, save only the pixels of the camera image that change. Do not save all pixels from all video frames. This technique was used in this ROS system.

Readability

Make code easy to understand and follow. Someone else should be able to look at your code and figure out what is going on.

Reliability

The system should behave as it is expected to behave. You can achieve good reliability by running many tests on the software to minimize the probability of future failure.

Resiliency

ROS 2 nodes should be able to handle gaps in sensor data as well as times when there is an overload of sensor data. Using an Extended Kalman Filter to estimate the robot’s state via a motion model is a good design choice.

Reusability

Write code so that it could easily be reused in an entirely different project.

Safety

Think about different scenarios that could cause the robot to do harm to a person or object, and write code to handle these scenarios (e.g. run into a wall at full speed).

Security

Add safeguards to the system to make it robust to tampering. 

Testability

Make it easy to debug your code and ensure the system is working correctly.

“Anything that can go wrong, will go wrong.”

Murphy’s Law

Think of all the ways that your code can break under abuse from users, and write test cases for those scenarios to see how your system holds up.

What Are the Most Important Attributes?

This paper mentions that maintainability, performance, and reliability (in order from most important to least important) are the most important attributes for a ROS-based system.

References

I. Malavolta, G. Lewis, B. Schmerl, P. Lago and D. Garlan, “How do you Architect your Robots? State of the Practice and Guidelines for ROS-based Systems,” 2020 IEEE/ACM 42nd International Conference on Software Engineering: Software Engineering in Practice (ICSE-SEIP), 2020, pp. 31-40.