C++ ROS catkin Package: Create, Write and Run it

Written for beginners and experts, this tutorial will show you how to use the catkin_create_pkg command to create a new ROS catkin package. It will also show you how to run it and after the C++ ROS package has been created. Additionally, a boilerplate is provided for you to write a ros package.

In fact, most official ROS packages are written in C++, like the motion planning library moveit or the navigation stack. If you want to interface them better, C++ is a better choice than Python, which has an additional layer to allow the Python interface.

Step 1 — Make sure you are in src catkin workspace directory

Before you begin, you will need to change to the source space directory (src) of the catkin workspace. This makes sure catkin and other commands (e.g., rospack, roscd, etc) can find your ROS packages.

cd ~/catkin_ws/src

If you have not created a ROS catkin workspace, the following is a quick reference. Note that it will create all the nessasary directories, such as src, devel, etc.

mkdir ~/catkin_ws/
cd ~/catkin_ws/
catkin init

Every ROS catkin package lives in the src directory of your catkin workspace, but you have the freedom to have packages in sub directories as well to organize several ROS packages.

Step 2 — Create a C++ catkin package

Now you can use the catkin_create_pkg script to create a new ROS catkin package, say move_robot, which should at least depends on roscpp and std_msgs to write ROS program in C++.

Do not append rospy as the official ROS tutorial did if you do not use Python…

roscpp is a ROS implementation in C++. std_msgs includes common ROS messages that mainly encapsulates primitive types, such as Bool, Char, String. See here for the full list.

catkin_create_pkg move_robot roscpp std_msgs

This will create a move_robot directory inside the src directory which contains a package.xml and a CMakeLists.txt, which have been partially filled out with the package name and dependency list you gave to catkin_create_pkg.

catkin_create_pkg requires that you pass a package name and optionally a list of dependencies on which that package depends.

# catkin_create_pkg <package> [dep1] [dep2] [dep3]

Step 3 — Minimum C++ ROS node boilerplate

“Node” is the ROS term for an executable that is connected to the ROS network. Here we’ll create a node_name node which is a boilerplate that you can copy and paste to each of our ROS project. You can name this file as node.cpp and put it in the src folder of your package.

#include "ros/ros.h"

int main(int argc, char **argv) {
  ros::init(argc, argv, "node_name");
  ros::NodeHandle n;
  ros::spin();
  return 0;
}

ros/ros.h is a convenience include that includes all the headers necessary to use the most common public pieces of the ROS system.

ros::init initializes ROS. This allows ROS to do name remapping through the command line — not important for now. This is also where we specify the name of our node.

Node names must be unique in a running system. The name used here must be a base name, i.e., it cannot have a / in it.

ros::NodeHandle n; creates a ROS handle to this process’ node. The first NodeHandle created will actually do the initialization of the node, and the last one destructed will cleanup any resources the node was using. This means you can have as many as ROS node handles without performance implications to create subscribers or publishers.

ros::spin() spins up your subscription, service and other callbacks so they will called and receive messages.

Step 3 — Edit CMakeLists.txt to prepare for package build

Actually catkin builds on top of cmake and adds a bunch of micros. You can learn cmake here: https://cmake.org/cmake/help/latest/guide/tutorial/index.html

Before we build the package, you can add the following few lines to the bottom of your CMakeLists.txt. Or you can search the cmake functions to make changes. The second ways is preferred as you gain more experience with ROS. But the first method is fine.

add_executable(node src/node.cpp)
target_link_libraries(node ${catkin_LIBRARIES})

Step 4 — Build the ROS C++ catkin package

Now you need to build the ros package in your catkin workspace. This step applies to any ROS packages, whether C++ or not. Note that we don’t use catkin_make because the catkin command is better in the sense that catkin_make may miss building dependencies.

You can build all packages using catkin build. Your current directory can be any directory in your workspace. catkin is smart enough to figure your catkin workspace directory out.

catkin build

Or you can build a specific ROS package. This is prefered as it can save compilation time, but it also means it won’t build the packages that your package may need or depend on.

catkin build move_robot

[tldr] 4 simple steps to create and run a C++ ROS catkin package

Reference:

This tutorial is adapted from http://wiki.ros.org/ROS/Tutorials/CreatingPackage from the ROS Wiki under Creative Commons Attribution 3.0. Significant original contribution is made to make life easier for beginners.

---