Naming and Organizing Packages in Large ROS 2 Projects

ros-cover

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!