Catkin and Packages

• Both spaces (referred to as result spaces) contain files generated from the build
• The devel space is designed for quick iteration during development while install is for releases.
• The devel space can use different compilation flags (such as debugging) than the install space
• The devel space is configured to access python scripts directly from the src. This means you don't need to rebuild every time your python code changes. With the install space, you would need to run catkin_make after every change.
  • However, I recommend running catkin_make as a matter of course when debugging
• The install space can be used to create and distribute your package as a binary. The ROS packages that you install using apt have been built by the ROS build farm and packaged as binaries from the install space.
• In this class, we will mostly be using the devel space.

There are three ROS 1 tools that can be used to build the workspace.

1. catkin_make This is the original tool and the one referred to most commonly. It is fast because it combines all the packages in the workspace into a single CMake project before compiling. We will use this because most documentation still refers to it and it is the fastest.
2. catkin_make_isolated: This tool was created due to REP-0134. Essentially, this builds each package as separate CMake projects, enabling projects that do not use catkin but rather just use CMake to be built as well. Some projects only build using this tool, and there is a slight preference for it. catkin_make_isolated uses devel_isolated and install_isolated for the development and install spaces (respectively).
3. catkin tools can be installed with apt install python3-catkin-tools.
   • It has the cleanest interface of the methods. This tool is technically in Beta and development has stopped; however it works well in practice.

• Workspaces can be created using mkdir -p <ws_name>/src. When you run the build tool for the first time, the result spaces will be created.
• It makes sense to have separate workspaces for every project you are working on.

Sometimes, ROS packages have bugs and you want to help fix them. Sometimes you need a new feature or slightly different behavior from a different package. The workspace mechanism provides a useful means of handling this case without needing to modify your base system.

1. Clone the repository you want to work on into the source space of a workspace.
   • Your packages that depend on that package will now use the compiled version, not the version installed on your system.
2. Modify the source code to suit your needs.
3. You can now submit a patch or, if the project is on github, you can fork the main repository, push your changes to your fork, and submit a pull request.

You create a package using catkin_create_pkg. After using this command, you usually need to edit the package.xml and CMakeLists.txt.

The package.xml is a file describing meta-data about the package. It is an XML document, which is specified here. There is also more information about how to properly write a package.xml in the catkin documentation.

• Information on the CMakeLists.txt is found here.
• The file generated by catkin_create_pkg is well commented, so reading the file helps explain what you need to do.
• Change the line with find_package(catkin REQUIRED COMPONENTS <dependencies>...) so that the <dependencies> match whatever is declared as a <depend> in your package.xml
• You should also change the catkin_package line to include the name of your catkin package dependencies
• If you use custom .msg or .srv files, there are further lines to uncomment so that the proper code will be generated. There are also lines in package.xml that should be edited.
• If you were using C++, you would need to add files to the add_executable statement to compile your nodes, and the add_library statement to compile your libraries.
• There is a section in the auto-generated CMakeLists.txt dedicated to installation. Lines in this section must be modified to properly be able to install your package.

• For each python node and executable script, you should add

  catkin_install_python(PROGRAMS nodes/prog1 nodes/prog2 ... DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})
  

  • This allows you to start your python scripts with the shebang #!/usr/bin/env python3 and have catkin replace it with the proper shebang for the system.

For a ROS packages, the general layout is as follows, where ${ros_pkg} is the base directory of the package

• The presence of two files, ${ros_pkg}/CMakeLists.txt and ${ros_pkg}/package.xml marks a directory as a ROS package
• ${ros_pkg}/scripts executable python scripts (useful utility scripts, not run as nodes).
• ${ros_pkg}/nodes executable python nodes (do not end with .py extension)
• The distinction between scripts and nodes is not made in all packages, and is somewhat of a preference
  • Usually scripts is used for executable code that is not a ROS node
  • In ROS, Python nodes start with a #!/usr/bin/env python and do not end in a .py extension (generally).
  • They must be installed with catkin_install_python in the CMakeLists.txt
• ${ros_pkg}/src contains python packages and C++ code.
• ${ros_pkg}/msg Message definitions
• ${ros_pkg}/srv Service definitions

1. ROS packages can contain one or more python packages. This is useful to allow the distribution of python packages that are tightly related to your ROS code
2. Let ${ros_pkg} be the name of a ROS package, and ${py_pkg} be the name of the python package.
3. Python packages go under ${ros_pkg}/src/${py_pkg}. Each ROS package can contain multiple python packages.
4. Create your python package under ${ros_pkg}/src/${py_pkg}. Everything in ${py_pkg} works as it does for any other python package.

5. Create a ${ros_pkg}/setup.py. It looks like the following and reads information from the package.xml

   from setuptools import setup
   from catkin_pkg.python_setup import generate_distutils_setup
   d = generate_distutils_setup(
       packages=['${py_pkg}'],
       package_dir={'': 'src'}
       )
   setup(**d)
   

6. Uncomment the catkin_python_setup() line in CMakeLists.txt
7. ${ros_pkg}/src/${py_pkg} is just like any other python package
   • It has a src/<pkg>/__init__.py, which can be a blank file most of the time
   • The package can be imported with import ${py_pkg}.
   • You can define a python module as src/${py_pkg}/module.py and import it as import ${py_pkg}.module
   • catkin takes care of the python path for you. If you have trouble importing a module, it is likely an issue with the catkin setup
8. Moving code into a python package (as opposed to leaving all code in the node) has several advantages
   1. You can import it into the python interpreter and work with it interactively
   2. It is easier to test
   3. It is easier to document (sphinx autodoc generally only documents packages not executable python files)
9. See the catkin documentation for more details:
   • Python Setup File
   • Installing Python

To create custom ROS message and service types, edit CMakeLists.txt and package.xml.

Conceptually there are three pieces required to generate messages and services:

1. Bring in all of the catkin machinery required to generate messages in general
2. Make catkin aware of all of the dependencies of your message/service
3. Tell catkin to process your message/service files and turn them into C++ and python code that can be used in your programs.

• catkin_lint is a tool used to help check that your CMakeLists.txt and package.xml have the required information and are synchronized.
• Install via apt install python-catkin-lint
• There is much redundancy between package.xml and CMakeLists.txt, and these files must be kept synchronized
  • It is very easy, for example, to require a dependency in CMakeLists.txt but not put it in your package.xml This will have consequences when distributing your package, such as rosdep not being aware of all dependencies.
  • The procedure to add custom messages and services is quite tedious, but catkin_lint not only detects errors in this setup but often tells you exactly what you need to do to fix them.
• catkin_lint src will check all the packages in your source space, or you can check an individual package by providing the path to that package
• I recommend using this tool on all your packages and fixing any errors it points out
• Most of the time, your package, especially if written in python, will work even if failing these checks; however, heeding checks helps ensure that other people won't have problems when trying to use your package.
• You can see an explanation for the warnings with the catkin_lint --explain option

• See all environment variables using env
• See all ROS environment variables using env | grep ROS, the | grep ROS part filters for variables containing the word ROS
• A scrollable list of environment variables is obtained using env | less. Press h for help and q for quit.
• The value of an individual variable can be printed using printenv VARNAME
• unset VARNAME clears an environment variable.

• The value can also be retrieved by prefixing the name with a $.

  > export VAR = 2
  > echo "Hello $VAR"
  Hello 2
  

• Each terminal has a different set of variables. Changing a variable in one terminal does not affect the other terminals.
• To set an environment variable "globally", add an export line to ~/.bashrc The commands in ~/.bashrc are run whenever your shell (the program that runs your commands entered at the command-line) starts. Thus every time you open the Terminal the variables that you set in .bashrc will be set.
• For more information see Linux Introduction

ROS relies on several environment variables to work.

• Running source /opt/ros/melodic/setup.bash in your ~/.bashrc sets the ROS variables to their initial values every time you start bash.
• When you activate the workspace using source devel/setup.bash you are primarily setting environment variables related to ROS
• ROS_ROOT stores the path to the core ROS packages
• ROS_MASTER_URI stores the location of rosmaster. By default this is http://localhost:11311.
• PYTHONPATH this tells python where to find packages. Sourcing devel/setup.bash sets this up properly for use with ROS. Modifying the python path to fix a problem is likely the incorrect action when using ROS.
• CMAKE_PREFIX_PATH tells CMake where to find everything required to build a cmake project. This is also used by catkin to find all of your packages and is set by setup.bash.
• ROS_IP/ROS_HOSTNAME Optional variables used for running nodes over the network. ROS_IP specifies the ip address for a node that is launched and ROS_HOSTNAME specifies the hostname for a node that is launched. Never set both of these as ROS_HOSTNAME overrides ROS_IP. If the computer you are running nodes on is accessible via hostname lookup from other computers on your network, you do not need to set these at all.
  • My recommendation is to always set up the network properly.
  • When buying a router, find one supported by https://openwrt.org/, which automatically allows name resolution on a local network.
  • If all computers in a network run the avahi-daemon, then they should be able to resolve each other as <hostname>.local.
• ROS_PACKAGE_PATH is a legacy variable that is not actually used; however, it will show the paths to your overlayed workspaces and is useful for debugging