Rules for programming with Python in ROS2

File Structure

colcon_workspace  
      |  
      |- build     (holds build files)
      |- install   (holds build elements)
      |- src       (contains your source code - this is where you work)

Colcon Build

Performing a colcon build is neccessary after every change to the src directory. This must be performed in the root of the colcon workspace (eg. cd ~/colcon_ws).

In order to avoid this procedure after every change made to a Python script you must run colcon build --symlink-install once. This links the files created in /build and /install to your source files in /src. However, after creating a new Python script this procedure must be repeated in order to also link this new script.

Source Directory

The source directory holds your ROS2 packages in the form of directories. In this example the src directory contains the exemplary packages pubsub and pubsub_msg:

colcon_workspace/
      |
      |- src/
          |
          |- pubsub/
          |- pubsub_msg/

The src directory is also the place where you create your new packages using ros2 pkg create ... and not in the root of the workspace.

The next chapters will describe the content of the files inside a package directory. However, the occuring files depend on the type of package (ament_cmake for C++ scripts or ament_python for Python scripts). This is described in detail here. The following chapters only describe Python packages (eg. pubsub/).

setup.py

The file setup.py is used to create entry points, meaning you link your python scripts to names which you can be called through ros2 run .... In order for this to work your python scripts must be written using the following mechanism

def main():
  # main code

if __name__ == "__main__":
  main()

in which you put all of your code inside main(). This prevents any code from being run, if this script is not run as main.

Linking your scripts to names is done inside the file setup.py by defining entry points:

entry_points={
   'console_scripts': [
       'talker = pubsub.talker:main',
       'listener = pubsub.listener:main'
   ],
},

The setup.py-excerp above links the the function main() from the scripts talker.py and listener.py from inside /pubsub to the names talker and listener. This way they can be called using ros2 run pubsub talker or ros2 run pubsub listener.

From this you can see that you need to follow the Python programming style of creating a main() procedure, in order for the entry points to work.

package.xml

The file package.xml is used to link dependencies to this package. For example, if this package requires a *.msg file which is located inside a different package this is defined in package.xml, eg.

                  colcon_workspace
                          |
  ---------------------------------------------------
  |                                                 |
pubsub    <---- depends on *.msg files ----<    pubsub_msg

This is also done in the background when creating a new package and defining dependencies
ros2 pkg create <pkg-name> --dependencies [deps]
for example
ros2 pkg create pubsub_2 --dependencies std_msgs builtin_interfaces --build-type ament_cmake
This command creates the new package pubsub_2 but already links it to the ROS standard messages std_msgs so they are available.

pubsub/

The example package pubsub/ contains a directory of the same name as the package. This is where you place your Python scripts. Inside this directory you are free to do as you please, however keep in mind that you need to link your main script (eg. listener.py) to a name later on (using setup.py).

3.8 KiB Raw Blame History