Tutorial: Build and run a new ROS package

Section

📜 Developing applications - tutorials

🏁 Goal of this tutorial

By the end of this tutorial, you will know how to develop a new ROS 2 package (C++ or Python) inside a Docker image.

Note

This page document ROS 2 programming, as found in PAL OS >= 24.06. If you are interested in ROS 1 development, check the ROS 1 documentation.

Pre-requisites

You need to be already familiar with ROS: if not, check the ROS tutorials.

In particular, you might want to check the colcon documentation, ament_cmake and ament_python if you are new to ROS 2 compilation and building tools.

Setup

This exercise can be done both in your development computer or inside the PAL docker container. During this tutorial we will be using the environment variables representing the ROS distribution and PAL distribution.

export PAL_DISTRO=alum
export ROS_DISTRO=humble

From your local environment create a new catkin workspace:

mkdir -p ~/example_ws/src

Now, let’s source the ROS environment depending on your development environment.

Local envDocker env

source /opt/ros/${ROS_DISTRO}/setup.bash

Create a ROS package

C++Python

cd /home/user/example_ws/src/
ros2 pkg create --build-type ament_cmake --license "Apache-2.0" --dependencies rclcpp std_msgs --node-name hello_world hello_world
cd hello_world

After running the command, your terminal will return the following :

going to create a new package
package name: hello_world
destination directory: /home/user/example_ws/src
package format: 3
version: 0.0.0
description: TODO: Package description
maintainer: ['user <user@todo.todo>']
licenses: ['Apache-2.0']
build type: ament_cmake
dependencies: ['rclcpp', 'std_msgs']
node_name: hello_world
creating folder ./hello_world
creating ./hello_world/package.xml
creating source and include folder
creating folder ./hello_world/src
creating folder ./hello_world/include/hello_world
creating ./hello_world/CMakeLists.txt
creating ./hello_world/src/hello_world.cpp

Implementing the node

Configure the package depending on your language

C++Python

In ROS 2, ament_cmake is default building tool, based on cmake.

In the following file we will be using ament_cmake_auto which is not well documented but you can find information on how to use it in the source code comments. This tools allow you to reduce boilerplate in cmake files.

Edit the CMakeLists.txt file with the following content:

CMakeLists.txt

cmake_minimum_required(VERSION 3.8)
project(hello_world)

if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
  add_compile_options(-Wall -Wextra -Wpedantic)
endif()

# find dependencies
find_package(ament_cmake_auto REQUIRED)
ament_auto_find_build_dependencies()

ament_auto_add_executable(hello_world src/hello_world.cpp)
target_compile_features(hello_world PUBLIC c_std_99 cxx_std_17)  # Require C99 and C++17

if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)
  # the following line skips the linter which checks for copyrights
  # comment the line when a copyright and license is added to all source files
  set(ament_cmake_copyright_FOUND TRUE)
  # the following line skips cpplint (only works in a git repo)
  # comment the line when this package is in a git repo and when
  # a copyright and license is added to all source files
  set(ament_cmake_cpplint_FOUND TRUE)
  ament_lint_auto_find_test_dependencies()
endif()

ament_auto_package()

From there you can add your different libraries in the package.xml and ament_cmake_auto would find them if required in your code.

Edit the src/hello_world.cpp file with the following content:

hello_world_node.cpp

#include "rclcpp/rclcpp.hpp"
#include "std_msgs/msg/string.hpp"

using namespace std::chrono_literals;

/* This example creates a subclass of Node and uses std::bind() to register a
* member function as a callback from the timer. */

class MinimalPublisher : public rclcpp::Node
{
  public:
    MinimalPublisher()
    : Node("minimal_publisher"), count_(0)
    {
      publisher_ = this->create_publisher<std_msgs::msg::String>("hello", 10);
      timer_ = this->create_wall_timer(
      500ms, std::bind(&MinimalPublisher::timer_callback, this));
    }

  private:
    void timer_callback()
    {
      auto message = std_msgs::msg::String();
      message.data = "Hello, world! " + std::to_string(count_++);
      RCLCPP_INFO(this->get_logger(), "Publishing: '%s'", message.data.c_str());
      publisher_->publish(message);
    }
    rclcpp::TimerBase::SharedPtr timer_;
    rclcpp::Publisher<std_msgs::msg::String>::SharedPtr publisher_;
    size_t count_;
};

int main(int argc, char **argv) {
  rclcpp::init(argc, argv);
  rclcpp::spin(std::make_shared<MinimalPublisher>());
  rclcpp::shutdown();
  return 0;
}

Building the package

Warning

Make sure to use a terminal where you did not source your workspace before building as mentionned in the documentation

Build the workspace in the same way, regardless if it is a Python or C++ script.

cd ~/example_ws
colcon build

Note

In order to avoid recompiling the whole workspace everytime you can run

colcon build --packages-up-to <package-name>

The expected output is shown below:

~/example_ws$ colcon build
Starting >>> hello_world
Finished <<< hello_world [1.29s]

Summary: 1 package finished [1.82s]

Note

If after compilation you have missing includes then you might want to run

rosdep install -iy --from-path PATH_TO_YOUR_WORKSPACE/src

Running node

In order to run the node, you first need to export the ROS_DOMAIN_ID of the robot and source the workspace. See robot-communication-ros2 for more information.

export ROS_DOMAIN_ID=<YOUR_ROBOT_DOMAIN_ID>
source install/setup.bash
ros2 run hello_world hello_world

Check if the message is correctly published by opening a new terminal or a new docker instance.

Local envDocker env

export ROS_DOMAIN_ID=<YOUR_ROBOT_DOMAIN_ID>
ros2 topic echo /hello

Next steps

• To run the package on your robot directly: Deploying ROS 2 packages on your robot

Related content

• For more information about ROS features refer to the ROS documentation