ros2-examples

Collection of examples about the main features and core subsystems of the Robot Operating System 2 robotics middleware, for tutorials or class materials.

Table of contents

• ros2-examples
  • Table of contents
  • Requirements
  • Usage guidelines
    • Docker containers
  • Code organization
    • List of examples
  • Additional resources
    • Useful references
  • Feedback
  • License
  • Copyright

Requirements

• Git (to clone this repository) (find a comprehensive tutorial from zero to hero here)
• ROS 2 Humble Hawksbill
• GCC toolchain (or any other C++ compiler that supports C++17)
• Python 3
• CMake
• Visual Studio Code (optional, other IDEs should work but the repository is built around VS Code)
• Docker (optional)

To clone this repository once you have Git installed, either use a GUI client or (better) run the following command in a terminal:

git clone https://github.com/IntelligentSystemsLabUTV/ros2-examples.git

and the repository will be cloned in the current directory, in a new directory called ros2-examples.

To update the repository’s contents, make sure to be in the humble branch (rember: git checkout enables you to switch branches) and run:

git pull

The contents of this repository were tested on a system running Ubuntu Linux 22.04, which is the officially supported host OS. You may as well be able to install ROS 2 on Windows and macOS, and thus run the examples on those platforms, but this is not guaranteed. Support for Windows is encouraged by means of the Windows Subsystem for Linux 2 (WSL 2), which allows you to run a Linux kernel on Windows hosts; the Ubuntu-22.04 distribution would be the best choice.

The repository is built around a Visual Studio Code template that you can find here, which automates many tasks that concern ROS 2 workspace organization and maintenance. It’s suggested that you play with this repository inside VS Code.

Usage guidelines

If this is the first time you hear about ROS 2, go have a look at the official documentation and some basic tutorials before proceeding. It is also recommended to have a look at the installation guide to get a grasp of the basic concepts and terminology.

The file bin/ros2_humble_install.sh contains a script that automates the installation of ROS 2 Humble Hawksbill on Ubuntu Linux 22.04. It is not guaranteed to work on other platforms, but it should be easy to adapt it to other Debian-based distributions.

The file config/ros2_cmds.sh contains a list of useful CLI commands to source the ROS 2 installation and its autocompletion scripts, which you can copy and paste in your .bashrc file to have them available in your shell; alternatively, you can source that file.

At this point, you should be able to build, run and modify all of the examples in this repository. It is strongly suggested that you create your own branch and work on that, so that you can always pull the latest updates from the humble branch without losing your work.

The following sections will provide a brief overview of the repository’s structure and contents.

Docker containers

This repository is based on the Distributed Unified Architecture, which provides support for Docker containers, so that you can run the examples without having to install ROS 2 on your host machine, and more. If you are interested, please find more information in the dua_template.md file.

According to the DUA target architecture, this repository offers the following containers:

• x86-dev
• x86-cudev
• armv8-dev

which are intended to provide a development environment on all major platforms, with all the limitations that come with each. In case you want to run code from this repository on a different machine using DUA containers, you can use the DUA configuration scripts to add targets as explained in the dua_template.md file.

Code organization

The format is simple: all the code is thoroughly documented, and comments marked with an exclamation mark are meant to explain what is happening in detail.

In C++ source files, you may find:

// This is a comment.
//! This is a comment that explains what is happening in detail.

whereas in Python code:

# This is a comment.
#! This is a comment that explains what is happening in detail.

Examples are provided for both C++ and Python, although the main focus of this project is on the former.

Expect this repository to be updated frequently, as it is meant to be a work in progress.

All source code is found in the src directory, which is organized as follows:

• cpp contains all the C++ code;
• python contains all the Python code;
• non-language-specific packages are found in the root src directory;
• the cpp/advanced and python/advanced directories contain examples that are more complex and are aimed at achieving a deeper understanding of ROS 2 by discussing some of its more advanced features.

File truncated at 100 lines see the full file