How to create a ros2 C++ Library

In this post, you will learn how to create and use your own ros2 C++ library. I’ll show you how to create the library and then use it in a demo package.

Step 1: Fire up a system with ROS2 installation

“Hey, do you mean I have to install ros2 first?” Absolutely not! Just log in to The Construct to get access to virtual machines pre-installed with ROS.

Once logged in, click on My Rosjects, then Create a New Rosject, supply the information as shown in the video and click Create. Then RUN the rosject.

You might also want to try this on a local PC if you have ros2 installed. However, please note that we cannot support local PCs and you will have to fix any errors you run into on your own. The rest of the instruction assumes that you are working on The Construct; please adapt them to your local PC and ros2 installation.

Step 2: Create a new package that contains the library’s source code (logic)

Open a web shell and run the following commands to create the package.

cd ros2_ws/src
source /opt/ros/humble/setup.bash/
ros2 pkg create my_value_converter_library --build-type ament_cmake --license BSD-3-Clause

Now that your package is created, we need to create a header file for the library. Move inside the include/my_value_converter_library directory and create a header file named library_header.h.  

cd ~/ros2_ws/src/my_value_converter_library/include/my_value_converter_library
touch library_header.h

Now head over to the Code Editor to make changes to the header file. Check the image below for how to open the Code Editor.

Locate the header file in the code editor: ros2_ws > src > my_value_converter_library > include > my_value_converter_library > library_header.h and paste in the following code.

#ifndef MAP_VALUE_H
#define MAP_VALUE_H

double map_value(double x, double in_min, double in_max, double out_min, double out_max);

#endif

Next, we create the C++ source code file for the library. In the same web shell:

cd ~/ros2_ws/src/my_value_converter_library/src
touch my_value_converter_library.cpp

Locate the my_value_converter_library.cpp file in the code editor and paste in the following code:

#include "my_value_converter_library/library_header.h"

double map_value(double x, double in_min, double in_max, double out_min, double out_max) {
  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}

Now we need to edit the CMakeLists.txt file of our package to recognize the source code we have just added. Open the file ros2_ws > src > my_value_converter_library > CMakeLists.txt and add the following lines before the ament_package() call.

# let the compiler search for headers in the include folder
include_directories(include)

# define a library target called my_value_converter_library
add_library(my_value_converter_library src/my_value_converter_library.cpp) 

# this line to exports the library
ament_export_targets(my_value_converter_library HAS_LIBRARY_TARGET)

# install the include/my_cpp_library directory to the install/include/my_cpp_library
install(
  DIRECTORY include/my_value_converter_library
  DESTINATION include
)

install(
  TARGETS my_value_converter_library
  EXPORT my_value_converter_library
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
  RUNTIME DESTINATION bin
  INCLUDES DESTINATION include
)

So much for all the hard work – now is the time to see if it works. Time to compile the code. In the same web shell, run the following commands:

cd ~/ros2_ws
colcon build

Success! We have now created our library. Next, we are going to use it!

PS: if your code did not compile correctly, please go over the instructions and ensure you have created the files in the exact locations specified.

Step 3: Create a new package that uses the library you just created

Create the new package in the open shell. Note that my_value_converter_library is passed as a dependency during the creation of the new package. This will simplify some of the work that needs to be done when modifying the CMakeLists.txt file.

cd ros2_ws/src
ros2 pkg create my_value_converter_node --build-type ament_cmake --license BSD-3-Clause --dependencies rclcpp std_msgs my_value_converter_library

Now verify that the dependencies have been properly added. If the build runs successfully, it is so. If not, please correct the errors before you proceed.

cd ~/ros2_ws
colcon build

If you got to this point, great! Now we will create the C++ source code that will use your library.

cd ~/ros2_ws/src/my_value_converter_node/src
touch my_value_converter_node.cpp

Now locate the my_value_converter_node.cpp file in the code editor and paste in the following source code.

#include <memory>
#include <string>

#include "my_value_converter_library/library_header.h"
#include "rclcpp/rclcpp.hpp"
#include "std_msgs/msg/float32.hpp"

class ConverterNode : public rclcpp::Node {
public:
  explicit ConverterNode() : Node("converter_node") {

    auto callback =
        [this](const std_msgs::msg::Float32::SharedPtr input_msg) -> void {
      RCLCPP_DEBUG(this->get_logger(), "I heard: [%f]", input_msg->data);

      // Use the library
      // Map an value from 0 - 1023 range to -1.0 to +1.0 range
      double new_value = map_value(input_msg->data, 0, 1023, -1.0, 1.0);

      output_msg_ = std::make_unique<std_msgs::msg::Float32>();
      output_msg_->data = new_value;
      RCLCPP_DEBUG(this->get_logger(), "Publishing: '%f'", output_msg_->data);
      pub_->publish(std::move(output_msg_));
    };

    sub_ = create_subscription<std_msgs::msg::Float32>("output_topic", 10,
                                                       callback);
    // Create a publisher
    rclcpp::QoS qos(rclcpp::KeepLast(7));
    pub_ = this->create_publisher<std_msgs::msg::Float32>("input_topic", qos);
  }

private:
  std::unique_ptr<std_msgs::msg::Float32> output_msg_;
  rclcpp::Publisher<std_msgs::msg::Float32>::SharedPtr pub_;
  rclcpp::Subscription<std_msgs::msg::Float32>::SharedPtr sub_;
};

int main(int argc, char *argv[]) {
  rclcpp::init(argc, argv);
  auto node = std::make_shared<ConverterNode>();
  RCLCPP_INFO(node->get_logger(), "My value converter node started.");
  rclcpp::spin(node);
  rclcpp::shutdown();
  return 0;
}

As you might have expected, we need to modify the CMakeLists.txt file for our new package. Locate the ros2_ws > src > my_value_converter_node > CMakeLists.txt in the code editor and paste in the following code before the ament_package() call.

# define the binary to be built and identify the source files with with which to build it
add_executable(main src/my_value_converter_node.cpp)
# tell CMake that the executable "main" depends on the library "my_value_converter_library"
ament_target_dependencies(main my_value_converter_library rclcpp std_msgs)
# install the executable in the lib folder to make it detectable through setup.bash
install(TARGETS 
  main
  DESTINATION lib/${PROJECT_NAME}/
)

Now build and use your package!

cd ~/ros2_ws
colcon build
source install/setup.bash

ros2 run my_value_converter_node main

Step 4: Check your learning

Do you understand how to create a ros2 C++ library? If you don’t know it yet, please go over the post again, more carefully this time.

(Extra) Step 5: Watch the video to understand how to install a ros2 binary package

Here you go:

Feedback

Did you like this post? Do you have any questions about how to create a ros2 C++ library? Please leave a comment in the comments section below, so we can interact and learn from each other.

If you want to learn about other ROS2 topics, please let us know in the comments area and we will do a video or post about it.

How to install a ros2 binary package

In this post, you will learn how to install a ros2 binary package and make it available for use. This post was written in response to this question on ROS Answers.

Step 1: Fire up a system with ROS2 installation

“Hey, do you mean I have to install ros2 first?” Absolutely not! Just login to The Construct to get access to virtual machines pre-installed with ROS.

Once logged in, click on My Rosjects, then Create a New Rosject, supply the information as shown in the video and click Create. Then RUN the rosject.

You might also want to try this on a local PC if you have ros2 installed. However, please note that we cannot support local PCs and you will have to fix any errors you run into on your own. The rest of the instruction assumes that you are working on The Construct; please adapt them to your local PC and ros2 installation.

Step 2: Check the ros2 binaries currently installed

Open a web shell and run the following commands. You should see a long list of many binaries!

cd /opt/ros/foxy/share/
ls -al

ROS binaries are stored in /opt/ros/{distro}/share/ If you would like to check if some binary is already installed without going through the long list, use grep. In this case we want to check binaries related to joint_state.

user:/opt/ros/foxy/share$ ls -al | grep joint_state
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_broadcaster
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_controller
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_publisher
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_publisher_gui

Heck, if you were the user in this post, you wouldn’t need to install anything. “What would I do then?!” Read on to find out!

Step 3: Install the ros2 binary package

We will demo this with the same package the user was struggling with: ros-foxy-joint-state-publisher-gui. Since the package is already installed in our case, we need to uninstall it first, just to demonstrate. Run the following on the current shell:

sudo apt update -y
sudo apt remove ros-foxy-joint-state-publisher-gui -y

Now verify that this GUI binary is no longer present.

user:/opt/ros/foxy/share$ ros2 pkg list | grep joint_state
joint_state_broadcaster
joint_state_controller
joint_state_publisher

Gone! Now we will install this package again.

sudo apt install ros-foxy-joint-state-publisher-gui -y

Before anything else, and this is probably what was missing for our friend who also installed the package successfully, SOURCE the ros2 distribution!

source /opt/ros/foxy/setup.bash

And that’s it! Installation complete. We are going to use the package now, but let’s check that it’s in the list of binaries.

user:/opt/ros/foxy/share$ ls -al | grep joint_state
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_broadcaster
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_controller
drwxr-xr-x  1 root root 4096 Sep 17  2021 joint_state_publisher
drwxr-xr-x  2 root root 4096 Oct 11 15:10 joint_state_publisher_gui

Step 4: Use the ros2 binary package

The user got an error when they tried to launch the GUI binary. Let’s see what we get (fingers crossed).

ros2 run joint_state_publisher_gui joint_state_publisher_gui

You should get a GUI like the image below pop up, confirming that the binary is really there. Cheers!

Step 5: Check your learning

Do you understand how to install a ros2 binary package and make it available for use? The magic word here is source.

If you didn’t get the point above, please go over the post again, more carefully this time.

(Extra) Step 6: Watch the video to understand how to install a ros2 binary package

Here you go:

Feedback

Did you like this post? Do you have any questions about how to install a ros2 binary package? Please leave a comment on the comments section below, so we can interact and learn from each other.

If you want to learn about other ROS2 topics, please let us know in the comments area and we will do a video or post about it.