Introduction to ROS2
Introduction to ROS2
The Robot Operating System (ROS) is a set of software libraries and tools that help you build robot applications. From drivers to state-of-the-art algorithms, and with powerful developer tools, ROS has what you need for your next robotics project. And it's all open source.
Robot Operating System (ROS) is a set of software libraries and tools that help you build robot applications. From drivers to state-of-the-art algorithms, along with powerful development tools, ROS provides everything you need for your next robotics project. And it's all open source.
ROS2 framework
ROS2 References
Official references
Since there are too few ROS2 reference documents, many tutorials still need to be viewed on the official ROS2 website:
Recommended Video Resources and Supporting Documentation
I highly recommend the following resources and videos.
https://www.bilibili.com/video/BV1VB4y137ys
Zhao Xuzuo's original supporting materials: ROS2 Theory and Practice - Zhao Xuzuo <Password: qinghuamengshi>.pdf
Unable to display this content outside of Feishu documents for now.
Knowledge reserves needed to learn ROS2
- What knowledge is needed?
- Linux Basic Operations and Shell Scripting Language
https://www.runoob.com/linux/linux-tutorial.html
4. Basic usage of CMake
Linux C++ Compilation Environment Setup
6. Git basic operations
Vinci Robotics Team Git Getting Started Tutorial
8. C/C++ language
Vinci Robot Team Electrical Control Group Beginner's Guide
Vinci Robotics Team C/C++ Resources
11. Python 3 language
Vinci Robotics Team Python3 Tutorial
https://www.runoob.com/python3/python3-tutorial.html
14. XML language
https://www.runoob.com/xml/xml-tutorial.html
16. YAML language
http://www.noobyard.com/article/p-saghdsms-mn.html
Install ROS2
For ROS1 installation, please refer to the Robot Operating System Tutorial.
** It is recommended to use Kubuntu 24.04 LTS ** ** It is recommended to learn the ROS2 Jazzy version. This tutorial will be based on ROS2 Jazzy **
Installing ROS2 from Binary Packages (Using Kubuntu Jammy 22.04 with ROS Humble as an Example)
Note:
As of December 2024, it is strongly recommended that if you are using ROS2, you must use ROS Humble and avoid ROS Jazzy. There are some differences, especially with Gazebo, which has almost no tutorials available.
For Ubuntu Jammy 22.04 (LTS), please install ROS Humble (LTS). Installation guide website: https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html
For Ubuntu Noble 24.04 (LTS), please install ROS Jazzy (LTS). Installation guide website: https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debians.html
ROS1 and ROS2 versions and their supported distributions: https://www.ros.org/reps/rep-2000.html
Go to the ROS official website
Be sure to install the LTS version of ROS2.
Preparations before installing ROS2
Install the LTS version of ROS2 by clicking to use the Debian package manager to install the ROS2 binary files.
Enter the following command in the terminal according to the ROS2 official website tutorial:
Still enter the following command to start the Ubuntu Universe Repo.
Switch source (domestic mirror)
This is the official source, which downloads ROS2 binary files from a foreign server. It has network requirements, so we need to change it to a domestic source.
Search Baidu for the Beijing Foreign Studies University mirror source (personally tested, the fastest source in the north).
Find ROS2, then check the boxes for sudo and https, and select the correct Linux distribution. Before running this command, you might encounter permission issues; you can look ahead to see how to run all commands with root privileges.
First, enter sudo passwd to set the root password (this is necessary for Ubuntu-based distributions) (for Debian, Fedora, and other distributions, the root password was already set during installation, so this step is not needed).
sudo passwd
su -
Then, under administrator privileges
Copy, paste, and run each line.
If the key download above gets stuck, it's likely due to GitHub being unreliable again — a very common issue. You can try using a proxy or VPN (proxy tutorial) to resolve it. If that still doesn't work, you can modify the hosts file by following the tutorial below.
After successfully downloading the key, proceed with the next steps.
Enter exit to exit root mode.
exit
Install ROS2 via apt
Run all of the following commands in the terminal, which are inside the red box.
The domestic mirror download is still very fast.
ROS2 basic environment variable configuration
Copy this line
Enter the following command
sudo apt-get install vim
sudo vim ~/.bashrc
At the very bottom, add this line (if you don't know how to use vim, please look it up on Baidu).
Refresh the environment variables of the current terminal.
echo 'export ROSDISTRO_INDEX_URL=https://mirrors.bfsu.edu.cn/rosdistro/index-v4.yaml' >> ~/.bashrc
source ~/.bashrc
Test ROS2
Please scroll down to the 测试ROS2 section.
Installing ROS2 from source (more difficult; for Ubuntu, just use the simple method above.)
Fedora or Rocky
Visit the official website and select the corresponding version, for example, I will choose ROS Jazzy here.
Then choose to compile from source, find the corresponding distribution, for example, I'm using Fedora here.
Then just follow the official tutorial.
- Set the area
Make sure your locale supports UTF-8. If you're in a minimal environment (like a Docker container), the locale might be something minimal like C. We tested with the following settings. However, if you're using another locale that supports UTF-8, it should be fine.
locale # check for UTF-8
sudo dnf install langpacks-en glibc-langpack-en
export LANG=en_US.UTF-8
locale # verify settings
- Enable the required repositories
Fedora does not require enabling additional repositories, while RHEL does.
- Install development tools
sudo dnf install -y \
cmake \
gcc-c++ \
git \
make \
patch \
python3-colcon-common-extensions \
python3-mypy \
python3-pip \
python3-pydocstyle \
python3-pytest \
python3-pytest-cov \
python3-pytest-mock \
python3-pytest-repeat \
python3-pytest-rerunfailures \
python3-pytest-runner \
python3-rosdep \
python3-setuptools \
python3-vcstool \
wget
# install some pip packages needed for testing and
# not available as RPMs
python3 -m pip install -U --user \
flake8-blind-except==0.1.1 \
flake8-class-newline \
flake8-deprecated
- Build ROS2
- Get the ROS2 source code
Find a folder to store ROS2. It is recommended to look in the /home partition, then open a terminal in this folder.
mkdir -p ./ros2_jazzy/src
cd ./ros2_jazzy
vcs import --input https://raw.githubusercontent.com/ros2/ros2/jazzy/ros2.repos src
```
5. Update the system
ROS 2 software packages are built on frequently updated Red Hat-based systems. It is always recommended to ensure your system is up to date before installing new software packages.
```cmake
sudo dnf upgrade
```
8. Initialize and change the rosdep source.
https://mirrors.bfsu.edu.cn/help/rosdistro/
```cmake
# 手动模拟 rosdep init
sudo mkdir -p /etc/ros/rosdep/sources.list.d/
sudo curl -o /etc/ros/rosdep/sources.list.d/20-default.list -L https://mirrors.bfsu.edu.cn/github-raw/ros/rosdistro/master/rosdep/sources.list.d/20-default.list
# 加入环境
echo 'export ROSDISTRO_INDEX_URL=https://mirrors.bfsu.edu.cn/rosdistro/index-v4.yaml' >> ~/.bashrc
# 加载.bashrc
source ~/.bashrc
# 更新rosdep
rosdep update
```
15. Install dependencies via rosdep
```cmake
export ROS_PYTHON_VERSION=3
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers"
```
If you encounter the error above, install the package using pip3.
```cmake
sudo pip3 install flake8-docstrings
```
Then, use the following command to ignore `flake8-docstrings`.
```cmake
rosdep install --from-paths src --ignore-src -y \
--skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-flake8-docstrings"
```
Once it shows success, that's all.
24. Environment setup (not needed for non-Red Hat distributions)
If you are using a Red Hat-based system, you need the following configuration.
You can temporarily define these macros using the following commands.
```bash
export RPM_PACKAGE_NAME=qt_gui_cpp # 根据包名调整（如 ros_<package>）
export RPM_PACKAGE_VERSION=1.0.0
export RPM_PACKAGE_RELEASE=1
export RPM_ARCH=$(uname -m)
```
|Variable name|Sample value|Usage|
|:---|:---|:---|
|RPM_PACKAGE_NAME|qt_gui_cpp|Define the RPM package name|
|RPM_PACKAGE_VERSION|1.0.0|Define the RPM package version|
|RPM_PACKAGE_RELEASE|1|Define the RPM package release number|
|RPM_ARCH|x86_64 or arm64|Define the target system architecture|
30. Build the source code using colcon.
```cmake
colcon build --symlink-install
```
Once the build is complete, the image below shows what it looks like when it finishes without errors.
5. Configure the basic environment
Find the folder below and copy its path. For example, mine is `~/UserFloder/Applications/ros2_jazzy`.
Use vim to modify the bash environment
```cmake
vim ~/.bashrc
Use the Insert key for input.
After adding these two lines, press ESC, then :wq to save and exit.
# 刷新当前环境变量
source ~/.bashrc
- Test ROS2
Please scroll down to the 测试ROS2 section.
Debian
Visit the official website and select the corresponding version, for example, I will choose ROS Jazzy here.
Then choose to compile from source, and find the corresponding distribution, for example, I'm using Debian here.
Next, starting from the diagram below, follow the official tutorial step by step. However, there are a few points to note, which I will list here:
- Set the area
locale # check for UTF-8
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8
locale # verify settings
- Change source
The red part is what needs to be done on Ubuntu; we are using Debian, so it's not necessary.
For the blue section, we should not use the official source, as it is an overseas source. Let's replace it with a domestic source.
First, switch to the mirror source:
https://mirrors.bfsu.edu.cn/help/ros2/
For example, I am using Debian 12:
sudo apt install curl gnupg2
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] https://mirrors.bfsu.edu.cn/ros2/ubuntu bookworm main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update
- After successfully changing the source in the image above, install the ROS tools:
sudo apt update && sudo apt install -y \
python3-flake8-blind-except \
python3-flake8-class-newline \
python3-flake8-deprecated \
python3-mypy \
python3-pip \
python3-pytest \
python3-pytest-cov \
python3-pytest-mock \
python3-pytest-repeat \
python3-pytest-rerunfailures \
python3-pytest-runner \
python3-pytest-timeout \
ros-dev-tools
- Download the ROS2 source code
Find a folder to store ROS2. It is recommended to look in the /home partition, then open a terminal in this folder.
mkdir -p ./ros2_jazzy/src
cd ./ros2_jazzy
vcs import --input https://raw.githubusercontent.com/ros2/ros2/jazzy/ros2.repos src
- Before adding dependencies, we need to initialize rosdep and change its source:
The red part in the image, don't follow that — it's the official source and will be very, very slow. It's recommended to use the BFSU repository instead.
https://mirrors.bfsu.edu.cn/help/rosdistro/
# 手动模拟 rosdep init
sudo mkdir -p /etc/ros/rosdep/sources.list.d/
sudo curl -o /etc/ros/rosdep/sources.list.d/20-default.list -L https://mirrors.bfsu.edu.cn/github-raw/ros/rosdistro/master/rosdep/sources.list.d/20-default.list
# 加入环境
echo 'export ROSDISTRO_INDEX_URL=https://mirrors.bfsu.edu.cn/rosdistro/index-v4.yaml' >> ~/.bashrc
# 加载.bashrc
source ~/.bashrc
# 更新rosdep
rosdep update
If you see the red boxed section above, it means the source has been successfully changed. If you don't change the source, the process of installing dependencies below might be extremely slow (I haven't tried it myself, but that's my guess), unless you have a VPN or proxy.
sudo apt upgrade
export ROS_PYTHON_VERSION=3
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers"
- Compile ROS2
In the ros_jazzy directory, open a terminal and run the following command.
colcon build --symlink-install
colcon build also has the following commands, such as --packages-skip and --packages-select, used to skip or compile individual packages.
Once the build is complete, the image below shows what it looks like when it finishes without errors.
- Configure the basic environment
Find the folder below and copy its path. For example, mine is ~/UserFloder/Applications/ros2_jazzy.
Use vim to modify the bash environment
vim ~/.bashrc
Use the Insert key for input.
# 配置ROS2环境
export ROSDISTRO_INDEX_URL=https://mirrors.bfsu.edu.cn/rosdistro/index-v4.yaml
source ~/UserFloder/Applcations/ros2_jazzy/install/setup.bash
After adding these two lines, press ESC, then :wq to save and exit.
# 刷新当前环境变量
source ~/.bashrc
- Test ROS2
Please scroll down to the 测试ROS2 section.
Installing ROS2 with Docker
Advanced ROS2 Installation (Optional)
The above only installed the most basic ROS2 packages and configured the most basic ROS2 environment.
After installing the above content, you can optionally proceed with the following advanced configuration of the ROS2 environment.
You can also skip installing advanced components and just install what you need as you learn. Of course, there are also those who prefer to get everything done at once, so below I'll list the most commonly used ROS 2 packages and environment configurations for a one-time installation.
https://index.ros.org/?search\_packages=true
Install advanced packages
Below are some of the navigation algorithms, simulation environments, and other packages that come with ROS2. These packages are listed below.
If you are using Ubuntu:
All of the packages below can be installed using apt, no need to compile manually!!!
If you are not using Ubuntu:
The gray ones are the packages installed in the basic tutorial above.
Yellow indicates packages that need to be manually compiled.
Blue indicates packages that require not only manual compilation but also manual modification of some source code.
| ROS packages (non-Ubuntu distributions generally require manual compilation) |
|---|
| Software package/library name |
| ros-humble-desktop |
| ros-humble-xacro |
| ros-humble-joint-state-publisher |
| ros-humble-joint-state-publisher-gui |
| ros-humble-gazebo-ros |
| ros-humble-gazebo-ros-pkgs |
| ros-humble-ros-gz |
| ros-humble-diagnostic-updater |
| ros-humble-teleop-twist-keyboard |
| ros-humble-navigation2 |
| ros-humble-nav2-bringup |
| ros-humble-slam-toolbox |
| ros-humble-cartographer |
| ros-humble-cartographer-ros |
| ros-humble-asio-cmake-module |
| ros-humble-serial-driver |
| ros-humble-pcl-ros |
| ros-humble-pointcloud-to-laserscan |
| ros-humble-vision-opencv |
| Non-ROS packages (most can be installed via apt, dnf) |
|---|
| Software package/library name |
| libpcl-dev |
| libeigen3-dev |
| libpcap-dev |
| libboost-dev |
| libogre-1.12-dev |
However, the packages mentioned above may depend on other packages. The repository below contains links to all the packages' repositories (read on to see how to use them):
https://github.com/ros/rosdistro/tree/master
APT installation method (strongly recommended for Ubuntu)
sudo apt update && sudo apt install \
ros-humble-desktop \
ros-dev-tools \
ros-humble-xacro \
ros-humble-joint-state-publisher \
ros-humble-joint-state-publisher-gui \
ros-humble-ros-gz \
ros-humble-gazebo-ros \
ros-humble-gazebo-ros-pkgs \
ros-humble-imu-tools \
ros-humble-diagnostic-updater \
ros-humble-teleop-twist-keyboard \
ros-humble-navigation2 \
ros-humble-nav2-bringup \
ros-humble-slam-toolbox \
ros-humble-cartographer \
ros-humble-cartographer-ros \
ros-humble-asio-cmake-module \
ros-humble-serial-driver \
ros-humble-pcl-ros \
ros-humble-vision-opencv \
ros-humble-pointcloud-to-laserscan \
libpcl-dev \
libeigen3-dev \
libpcap-dev \
python3-colcon-common-extensions
Source code method (non-Ubuntu)
Using Debian 12 as an example.
Yellow bag
Using the installation of the three packages ros-jazzy-xacro, ros-jazzy-joint-state-publisher, and ros-jazzy-joint-state-publisher-gui as an example, the same procedure applies to other packages.
https://index.ros.org/?search\_packages=true
Go to the website above, select the corresponding version in the image below — for example, I'm using JAZZY — then search for xacro, joint_state_publisher, and joint_state_publisher_gui in the search box.
For example, xacro
Find the corresponding version of xacro, where the repository address is the checkout URI and the branch is the vcs version. You could use git clone to clone them one by one, but that would be extremely tedious. So we choose the vcs command provided by ROS2 to download the source code of the packages.
First, navigate to your ros2_jazzy directory and open a terminal.
and create a .repos file, name it whatever you like, for example I'll call mine my_ros2_jazzy_packages.repos
Then edit it using VSCode, because .repos uses the YAML language, and VSCode can verify syntax correctness:
Write the information you just queried onto it.
repositories:
xacro:
type: git
url: https://github.com/ros/xacro.git
version: ros2
Use the same method to find other packages:
The image above explains that joint_state_publisher and joint_state_publisher_gui are actually from the same repository, so we only need to clone one repository.
Then the VCS version, which is the Git branch, is ros2.
repositories:
xacro:
type: git
url: https://github.com/ros/xacro.git
version: ros2
joint_state_publisher:
type: git
url: https://github.com/ros/joint_state_publisher.git
version: ros2
Apply the same method to other packages.
But let me first use these two packages as an example.
In the terminal under the ros2_jazzy directory:
vcs import src < my_ros2_jazzy_packages.repos
You can see in the image below that the clone was successful.
Next, supplement the dependencies:
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers"
If the text shown in the image below appears, it means success.
Just compile and install it.
colcon build --symlink-install
# 或仅编译特定包
colcon build --packages-select xacro joint_state_publisher joint_state_publisher_gui
Apply the same method to other packages.
Test:
# 重新加载环境
source ~/.bashrc
# 敲命令
xacro
As shown in the figure below, if xacro prompts an error, that means it's successful. This indicates the installation was successful!
Apply the same method to other packages.
I also put together the repos files for Humble and Jazzy, pulling them one by one from the official website and distribution.yaml. You can just clone and use what I've organized. (Though the ROS2 official team might make changes to some repository branches.)
https://github.com/tungchiahui/ros-docker/tree/main/repos
Blue bag
The blue package is generally handled in the same way as the yellow one, except that after downloading the source code for the blue package, you also need to modify some files in the source code before compiling.
For vision_opencv's cv_bridge: see the CV_Bridge section in the OpenCV chapter below.
Frequently Asked Questions
- libogre-dev not found
Gazebo's rendering engine cannot be found using libogre-dev on Debian 12; you must use libogre-1.12-dev instead.
- In nav2_mppi_controller, a null pointer was being treated as an error, causing a warning to be escalated into an error.
Simply add add_compile_options(-Wno-error=null-dereference) to the CMakeLists.txt of nav2_mppi_controller to resolve the issue.
- There is a memory overlap warning in nav2_system_tests.
To resolve this, simply add the following lines to the CMakeLists.txt file in nav2_system_tests.
if (CMAKE_CXX_COMPILER_ID MATCHES "GNU")
add_compile_options(-Wno-restrict)
endif()
- Some libraries are not available in the latest version of Fedora, but are present in older versions.
https://src.fedoraproject.org/projects/rpms/%2A
sudo dnf install python3-pykdl --releasever=41
sudo dnf install orocos-kdl-devel --releasever=41
- Some Python libraries cannot be installed on the latest version of the system because the Python version is too high.
You can install this library using pip3.
pip3 install flake8-docstrings
However, for subsequent compilation, this library needs to be added to the dependencies ignored by rosdep. For example, for python3-flake8-docstrings, the line would be:
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers"
# 改为
rosdep install --from-paths src --ignore-src -y --skip-keys "fastcdr rti-connext-dds-6.0.1 urdfdom_headers python3-flake8-docstrings"
Advanced Environment
Apt method
# rosdep换源
export ROSDISTRO_INDEX_URL=https://mirrors.bfsu.edu.cn/rosdistro/index-v4.yaml
# 加载ROS2环境
source /opt/ros/jazzy/setup.bash
# 配置ROS2的分布式
export ROS_DOMAIN_ID=6
# 配置新版Gazebo的资源（这里先注释，等你学到gazebo再打开）
#export GZ_SIM_RESOURCE_PATH=$GZ_SIM_RESOURCE_PATH:/home/tungchiahui/UserFloder/MySource/ROS_WS/gazebo_models:/home/tungchiahui/UserFloder/MySource/ROS_WS/ign_models
Note that the macro name for Gazebo resource packages may differ across ROS2 versions. For example, in ROS2 Humble it is IGN_GAZEBO_RESOURCE_PATH, while in ROS2 Jazzy it is GZ_SIM_RESOURCE_PATH. (Future ROS2 versions will likely all use GZ_SIM_RESOURCE_PATH.) (See the Gazebo tutorial below for details.)
Source code method
The method is the same as with apt, but you need to set the path to the setup.bash that loads the ROS2 environment to your ROS2 installation path.
# 加载ROS2环境
source ~/UserFloder/Applcations/ros2_jazzy/install/setup.bash
Test ROS2
Example 1
Open two terminals, and enter the commands shown in the two red boxes respectively.
If the following program appears, the test is successful.
Press Ctrl+C in the terminal to terminate the program.
Example 2
Turtle is a classic ROS test project, so it's a must to take it for a spin!
Open two terminals as well, and enter the following commands in each respectively.
ros2 run turtlesim turtlesim_node
ros2 run turtlesim turtle_teleop_key
Click the red section below with the mouse, then use the arrow keys on the numeric keypad to control the turtle's movement. If you don't have a numeric keypad, you can try using keys like G, B, V, C, D, E, R, T to control the turtle.
Similarly, pressing Ctrl+C in the terminal will terminate the program.
Frequently Asked Questions
Rviz2 flickering
If a 2K+ computer has display issues after installing rviz2, you can add the following content to .bashrc to prevent Qt from scaling.
export QT_AUTO_SCREEN_SCALE_FACTOR=0
export QT_SCREEN_SCALE_FACTORS=[1.0]