CSCE 452/752: Notes on ROS2 workspaces and packages

For Project 1, you will need to write a small program that is part of a fully-formed ROS package. Though organizing your ROS code into packages is not strictly necessary to use ROS —especially if you are writing in an interpreted language like Python— but it gives a few benefits. These benefits increase as the system becomes more complex. Thus, Project 1 requires you to use this practice, to ensure you know how it works.

This document contains a quick overview of workspaces and packages in ROS2, focused on some of the specifics you'll need to complete Project 1.

Creating a workspace and a package

The first step is to create a workspace and a package within that workspace. This is covered well in the official documentation, so we won't repeat those steps here:

Adding code to the package

After creating the workspace and package, add the Python code for your ROS node(s) to the package. The recommended file organization is to place these programs three levels deep:

Within your workspace, in
src
subdirectory for the workspace.
Within that
src
subdirectory, a package source subdirectory with the same name as your package.
Within that package source subdirectory, another subdirectory with the same name as your package.

For example, my ROS workspace is called

ros_ws

, my Project 1 package is called

project1

, and my program is called

circle.py

. So I created a directory called

ros_ws/src/project1/project1

and placed the

circle.py

source code in that directory:

ros_ws/src/project1/project1/circle.py

Creating an entry point

Next, you should declare your program as an “entry point” for the package, so that

ros2 run

can locate and execute the program. This is done by modifying the package's

setup.py

, adding an element to the

entry_points

list, which is empty by default.

In my example, the

entry_points

block looks like this:

entry_points={
    'console_scripts': [
        'circle = project1.circle:main',
    ],
}

This indicates that a command called

circle

should exist, and when that command is run, it should execute the function called

main

in the

circle

module inside the

project1

Python package. If you have more than one program, you can add multiple entries to this list.

Building the package

After adding your program to the package, you should build the package. This step uses the package configuration to assemble all of the parts of the complete package in a place where the

ros2

runtime system can locate them. (For programs written in compiled languages like C++, this step is also where the compilation process happens.)

To build after the package setup is complete, run this command in your workspace directory:

colcon build

Then activate that setup, incorporating your new package and the program within it into ROS system in the active terminal:

source install/setup.bash

If all of the steps above have worked correctly, you should see your package included alongside the standard ROS packages in the output of

ros2 pkg list

You should also be able to start your project using

ros2 run

. For example, I can use the command

ros2 run project1 circle

to start my program.

If you modify things within your package, the

colcon build

step should be repeated to ensure that the latest versions are available to ROS.

This page from the official documentation has a few more details about building packages:

Using
colcon
to build packages