Tutorial 4: Communications using services

Objective: This tutorial session is devoted to learn the ROS request/response remote procedure calls.

Contents

Communication features

Action interfaces

A client program

A server program

EXERCISE 4

After this session you will be able to:

• Understand the client/server mechanism.

• Use the rqt service type browser tool to look for the standard service types.

• Define non-standard services: the .srv files and the required commands in the CMakeLists.txt and package.xml files.

• Write nodes able to call/offer a service..

References:

• Chapters 3 and 4 of the book A very informal journey through ROS 2 Marco Mateo Bassa (examples: https://github.com/nirwester/ros2_journey_examples).

Complementary resources:

• The ROS 2 basic concepts: Services

• The ROS 2 basic tutorials: Understanding Services

• The ROS 2 how-to guides: Synchronous vs. asynchronous service clients

• The ROS 2 tutorial on Writing a simple service and client (C++)

• The ROS 2 tutorial on Creating custom msg and srv files

• The ROS 2 tutorial on Implementing custom interfaces

Provided packages:

This tutorial will use the following package:

Package foolturtle_server

Package foolturtle_server_interfaces

Package foolturtle_server_alone

Package urdf_tutorial

Package kinenikros2

Package rviz2_marker_demo

Package ur_description

Prepare the colcon workspace to work with it:

1. If you have not yet done so, follow the steps in Setup to:

• clone in your ~/data/git-projects folder the meta-repository containing all the required packages,

• create the colcon workspace folders (use colcon_ws4 for the current tutorial).

2. Follow the procedure shown in Procedure to prepare the exercises to import in the intro2ros/2025/teamXX/EXERCISE4 subgroup of your GitLab account the package you implemented to solve exercise 3 (change XX by your team number):

• urdf_tutorial: https://gitlab.com/intro2ros/2025/teamXX/exercise3/urdf_tutorial.git

3. In your git-projects folder clone the urdf_tutorial project of your GitLab account inside an exercise4 subfolder (change XX by your team number). You can use https:

git clone https://gitlab.com/intro2ros/2025/teamXX/exercise4/urdf_tutorial.git exercise4/urdf_tutorial

or ssh:

git clone git@gitlab.com:intro2ros/2025/teamXX/exercise4/urdf_tutorial.git exercise4/urdf_tutorial

4. In your colcon_ws4/src folder create a symbolic link to the package to be used:

ln -s ~/data/git-projects/all_introduction_to_ros2_packages/foolturtle_server
ln -s ~/data/git-projects/all_introduction_to_ros2_packages/foolturtle_server_interfaces
ln -s ~/data/git-projects/all_introduction_to_ros2_packages/foolturtle_server_alone
ln -s ~/data/git-projects/exercise4/urdf_tutorial
ln -s ~/data/git-projects/all_introduction_to_ros2_packages/kinenikros2
ln -s ~/data/git-projects/all_introduction_to_ros2_packages/rviz2_marker_demo
ln -s ~/data/git-projects/all_introduction_to_ros2_packages/Universal_Robots_ROS2_Description

Communication features

In ROS 2, a service refers to a remote procedure call, i.e., a node (the service client) makes a remote procedure call (called a request) to another node (the service server) which takes some action (computing something, configuring hardware or software, changing its own behavior, etc.) and returns a result (called a response).

ROS service calls communication has the following features:

• It is bi-directional.

• It one-to-one.

• The calls are usually expected to return quickly, as the client is generally waiting on the result.

• Are identified by a service name (there should only ever be one service server per service name).

A service data type determines the content of messages by a collection of named fields, and is divided into two parts, the request and the response, e.g., for a request composed by an integer and a string and a Bool as a response, it would be specified as:

uint32 number
string name
---
bool result

Exercise

Run the turtlesim_node:

ros2 run turtlesim turtlesim_node

Inspect the /spawn service and its interface:

ros2 service list
ros2 service type /spawn
ros2 interface show turtlesim/srv/Spawn

Call the service from the terminal:

ros2 service call /spawn turtlesim/srv/Spawn "{x: 1.0, y: 1.0, name: Speedy}"

Note that the service type has to be added to the call.

Recall that you can use the tab to autocomplete.

Service interfaces

Standard services

The std_srvs package contains three service types called Empty, SetBool and Trigger, which are common service patterns for sending a signal to a ROS node.

• The Empty service does not exchange any actual data between the service and the client.

• The SetBool service is used to set bolean values.

• The Trigger service adds the possibility to check if triggering was successful or not.

Exercise

Use the rqt tool to browse the std_srvs types:

$ rqt -s rqt_srv

Non-standard services

To allow a server to offer services with customized arguments and return values, a text file (with extension .srv) is generated with the input and output message types, e.g. here we will use a service (called ChangeVel) to change the maximum velocity to be commanded to a turtle in a turtlesim_node:

  float32 max_vel
  ---
  bool ret
  float32 time_of_change

Some naming conventions have to be followed for defining interfaces:

• Naming of messages and services: Each file contains a single message or service. Message files use the extension .msg, service files use the extension .srv. Both file names must use an upper camel case name and only consist of alphanumeric characters.

• Naming of fields: Field names must be lowercase alphanumeric characters with underscores for separating words. They must start with an alphabetic character, they must not end with an underscore and never have two consecutive underscores.

  Note that also the standard message types are lowercase, e.g. float64, while the standard messages that wrap them have the first letter uppercase, e.g. Float64.

• Header files: The files generated from message generation are snake case (i.e. the names of the header files are all lowercases and include an underscore before every upercase in the original camelcase name).

Defining services in a dedicated package

In section Custom messages we created a separate package to define a custom message, because it is a good practice to define the interfaces of a package (the custom messages, services and actions) in a separate package.

If a package is called my_package then the interfaces will be defined in a package called my_package_interfaces.

In order to generate new custom messages and services and make them available to other packages, the use of rosidl packages is required. These packages contain a set of tools and libraries to define interfaces (message types, services and actions).

For this, the CMakeLists.txt file should have the following lines:

#  Add the following lines to generate the interfaces (msg and srv)
find_package(rosidl_default_generators REQUIRED)
set(msg_files
   "msg/MyMessage.msg"
   )
set(srv_files
   "msg/MyService.srv"
   )
rosidl_generate_interfaces(${PROJECT_NAME}
   ${msg_files}
   ${srv_files}
   #DEPENDENCIES xxxxxx  Add here any package that above messages may depend on, e.g. geometry_msgs
)

And the package.xml file should have the following lines:

  <!--Add the following four lines to generate custom messages and services-->
  <buildtool_depend>rosidl_default_generators</buildtool_depend>
  <exec_depend>rosidl_default_runtime</exec_depend>
  <member_of_group>rosidl_interface_packages</member_of_group>

Exercise

Take a look at the package foolturtle_server_interfaces:

• the srv folder

• the CMakeLists.txt file

• the package.xml file

Exercise

Build the foolturtle_server_interfaces package and check the availability of the service ChangeVel:

colcon build --packages-up-to foolturtle_server_interfaces
ros2 interface show foolturtle_server_interfaces/srv/ChangeVel

Then, the package using these interfaces should include the dependency in the CMakeLists.txt file:

  find_package(my_package_interfaces REQUIRED)
  set(dependencies
   ....
   my_package_interfaces
  )

And also in the package.xml the dependency on this package should be made explicit:

<depend>my_package_interfaces</depend>

Exercise

Take a look at the package foolturtle_server that will use the services defined in foolturtle_server_interfaces:

• the CMakeLists.txt file

• the package.xml file

Defining services in the same package

For small packages with simple services, these can be defined in the same package, i.e. the package will include a srv folder with the definition of the services (likewise if custom messages where necessary):

my_package/
   package.xml
   CMakeLists.txt
   include/my_package/
   src/
   srv/

The CMakeLists.txt file will need to be extended by adding lines 1, 17-21 below. The rosidl_get_typesupport_target() returns the name of a typesupport target, which is used in a target_link_libraries() call to make the target depend on generated code for interfaces generated in the same CMake project.

find_package(builtin_interfaces REQUIRED)

#  Add the following lines to generate the interfaces (msg and srv)
find_package(rosidl_default_generators REQUIRED)
set(msg_files
   "msg/MyMessage.msg"
   )
set(srv_files
   "msg/MyService.srv"
   )
rosidl_generate_interfaces(${PROJECT_NAME}
   ${msg_files}
   ${srv_files}
   #DEPENDENCIES xxxxxx  Add here any package that above messages may depend on, e.g. geometry_msgs
)

# Use generated message in own package
rosidl_get_typesupport_target(cpp_typesupport_target
         ${PROJECT_NAME} rosidl_typesupport_cpp)
# Link against the interface
target_link_libraries(publish_address_book "${cpp_typesupport_target}")

The package.xml file should include the line 6 below to show the build dependance on the package builtin_interfaces:

  <!--Add the following four lines to generate custom messages and services-->
  <buildtool_depend>rosidl_default_generators</buildtool_depend>
  <exec_depend>rosidl_default_runtime</exec_depend>
  <member_of_group>rosidl_interface_packages</member_of_group>
  <!--Add the following four lines to generate custom messages and services inside the package-->
  <build_depend>builtin_interfaces</build_depend>

More details in this ROS 2 tutorial section: Use an interface from the same package.

Exercise

Take a look at the package foolturtle_server_alone:

• the srv folder

• the CMakeLists.txt file

• the package.xml file

A server program

The foolturtle_server package

This package is an variant of the package foolturtle that, besides having the pubsub node publishing random velocities to command the motion of a turtle1, it also offers a service to change the maximum absolute velocity.

The definition of the service is done in the foolturtle_server_interfaces package.

The package also has different clients to call this service, as commented below.

The code of pubsub node that defines a service to change the maximum value of the published random command is shown next.

Note:

• The header file included: #include “foolturtle_server_interfaces/srv/change_vel.hpp”

• The change_vel service created in lines 24-25.

• The change_vel_callback function to be called when a request to the service is received (a random delay has been added to test later the client behaviors).

  #include "rclcpp/rclcpp.hpp"
  #include "geometry_msgs/msg/twist.hpp"
  #include "foolturtle_server_interfaces/srv/change_vel.hpp"
  #include "rclcpp/duration.hpp"
  #include <stdlib.h> // For rand() and RAND_MAX
  #include <chrono>
  #include <thread>

  using namespace std::chrono_literals;
  using std::placeholders::_1;
  using std::placeholders::_2;

  class PublisherNode : public rclcpp::Node
  {
     public:
     PublisherNode() : Node("pubvel_node")
     {
        pubvel_ = create_publisher<geometry_msgs::msg::Twist>("turtle1/cmd_vel", 10);
        //to set a publishing frequency of 2Hz
        timer_ = create_wall_timer(
           500ms, std::bind(&PublisherNode::timer_callback, this));
        //seed the random number generator.
        srand(time(0));
        //create the service
        change_vel_service_ = create_service<foolturtle_server_interfaces::srv::ChangeVel>("change_vel",
                 std::bind(&PublisherNode::change_vel_callback, this, _1, _2));
        maxvel_ = 1.0;
     }

     void timer_callback()
     {
        // Create and fill in the message.  The other four
        // fields, which are ignored by turtlesim, default to 0.
        msg_.linear.x = double(rand())*maxvel_/double(RAND_MAX);
        msg_.angular.z = 2*double(rand())*maxvel_/double(RAND_MAX) - 1;
        pubvel_->publish(msg_);
        // Send a message to rosout with the details.
        RCLCPP_INFO_STREAM(get_logger(), "Sending random velocity command:"
           << " linear=" << msg_.linear.x
           << " angular=" << msg_.angular.z);
     }

     bool change_vel_callback(const std::shared_ptr<foolturtle_server_interfaces::srv::ChangeVel::Request> request,
              std::shared_ptr<foolturtle_server_interfaces::srv::ChangeVel::Response> response)
     {
        //add some extra random delay ranging from 1s to up to 4s
        // Set the delay time in seconds (expressed as a float number)
        float delay_seconds = 1.0+double(rand())*3/double(RAND_MAX);
        RCLCPP_INFO_STREAM(get_logger(), "change_vel_callback will be delayed by " << delay_seconds );
        // Convert the delay time to nanoseconds and create a Duration object
        auto delay_duration = std::chrono::duration_cast<std::chrono::nanoseconds>(
           std::chrono::duration<float>(delay_seconds));
        std::this_thread::sleep_for(delay_duration);

        //use the request values and set the response
        maxvel_ = request->max_vel;
        response->ret = true;
        response->time_of_change = get_clock()->now().seconds();
        RCLCPP_INFO_STREAM(get_logger(), "MAXIMUM VELOCITY CHANGED TO " << maxvel_ );
        return true;
     }

     private:
        rclcpp::Publisher<geometry_msgs::msg::Twist>::SharedPtr pubvel_;
        rclcpp::Service<foolturtle_server_interfaces::srv::ChangeVel>::SharedPtr change_vel_service_;
        rclcpp::TimerBase::SharedPtr timer_;
        geometry_msgs::msg::Twist msg_;
        double maxvel_;
  };

  int main(int argc, char * argv[])
  {
     rclcpp::init(argc, argv);

     auto node = std::make_shared<PublisherNode>();
     rclcpp::spin(node);
     rclcpp::shutdown();
     return 0;
  }

Exercise

Build the foolturtle_server package, run the turtlesim_node and pubsub nodes and call the service from the terminal:

colcon build --packages-up-to foolturtle_server
source install/setup.bash
ros2 run turtlesim turtlesim_node
ros2 run foolturtle_server pubvel
ros2 service call /change_vel foolturtle_server_interfaces/srv/ChangeVel "{max_vel: 5.0}"

The foolturtle_server_alone package

The foolturtle_server_alone package has the same functionality as the foolturtle_server package but now the definition of the service is done in the same foolturtle_server_alone package.

A client program

The service calls in ROS 2 services are asynchronous. The client thread is not stuck when calling the service, since the service call immediately return future, a value that indicates whether the call and response is finished (not the value of the response itself).

The future variable can be queried for the response in different ways, giving rise to different behaviors:

• By waiting until a response is available, which makes the service call synchronous.

• By iteratively checking the status of the variable

• By using a callback to handle the response.

These are analyzed in the following subsections.

Synchronous calls

A synchronous client will block the calling thread when sending a request to a service until a response has been received; nothing else can happen on that thread during the call. The call can take arbitrary amounts of time to complete. Once complete, the response returns directly to the client.

To call a service in this way the rclcpp::spin_until_future_complete function should be used:

  auto result = service_client_->async_send_request(request);
  // Wait for the result.
  if (rclcpp::spin_until_future_complete(this->get_node_base_interface(), result) ==
    rclcpp::FutureReturnCode::SUCCESS)
  {
    //Service called - Response received
    auto my_result = result.get();
    ....
  } else {
    //Failed to call the service
    ....
  }

Take a look at the client.cpp file of the foolturtle_server package:

  #include "rclcpp/rclcpp.hpp"
  #include "foolturtle_server_alone/srv/change_vel.hpp"

  using namespace std::chrono_literals;

  class ClientNode : public rclcpp::Node
  {
     public:
     ClientNode() : Node("client_node")
     {
        //create the client
        change_vel_service_client_ = create_client<foolturtle_server_alone::srv::ChangeVel>("change_vel");
        //setup the scene
        change_vel_turtle("turtle1", 2.0);
     }
     void change_vel_turtle(std::string turtlename, float maxvel)
     {
        auto request = std::make_shared<foolturtle_server_alone::srv::ChangeVel::Request>();
        request->max_vel = maxvel;

        //spawn_client_.
        while (!change_vel_service_client_->wait_for_service(1s)) {
           if (!rclcpp::ok()) {
           RCLCPP_ERROR(rclcpp::get_logger("rclcpp"), "Interrupted while waiting for the service. Exiting.");
           return;
           }
           RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "ChangeVel service not available, waiting again...");
        }

        auto result = change_vel_service_client_->async_send_request(request);
        // Wait for the result.
        if (rclcpp::spin_until_future_complete(this->get_node_base_interface(), result) ==
           rclcpp::FutureReturnCode::SUCCESS)
        {
           RCLCPP_INFO(rclcpp::get_logger("rclcpp"), "Velocity of turtle %s set to %f", turtlename.c_str(), maxvel);
        } else {
           RCLCPP_ERROR(rclcpp::get_logger("rclcpp"), "Failed to call service ChangeVel");
        }
     }

     private:
        rclcpp::Client<foolturtle_server_alone::srv::ChangeVel>::SharedPtr change_vel_service_client_;
  };

  int main(int argc, char * argv[])
  {
     rclcpp::init(argc, argv);

     auto node = std::make_shared<ClientNode>();
     //rclcpp::spin(node);

     //Change the maxvel of the turtle each 5 seconds by calling the change_vel_turtle service
     //with a random max value between 1 and 5.
     rclcpp::Rate rate(0.2);
     double maxvel;
     while(rclcpp::ok()){
        maxvel = 1.0+double(rand())*5/double(RAND_MAX);
        rclcpp::spin_some(node);
        RCLCPP_INFO( node->get_logger(), "MAX VEL set to %f", maxvel);
        node->change_vel_turtle("turtle1", maxvel);
        rate.sleep();
     }

     rclcpp::shutdown();
     return 0;
  }

Exercise

Take a look at this example https://github.com/ros2/examples/blob/humble/rclcpp/services/minimal_client/main.cpp

Asynchronous calls

Async calls are entirely safe and the recommended method of calling services. They can be made from anywhere without running the risk of blocking other ROS and non-ROS processes, unlike sync calls.

One option is to wait for the answer for a while and then check the status of the variable future:

• The method wait_for returns std::future_status::ready if a response has been received while waiting the specified amount of time; if this time is elapsed without response then the method returns std::future_status::timeout.

   auto result = service_client_->async_send_request(request);
   //auto status = result.wait_for(5s);//if the node is spinning
   auto status = result.wait_for(50ms);
   for(int i=0; i<100;i++){
     rclcpp::spin_some(this->get_node_base_interface());
     status = result.wait_for(50ms);
     if(status != std::future_status::ready) break;
   }

   bool success = false;

   if (status == std::future_status::ready) {//get the result
     auto my_result = result.get();
     ....
   }
   else{// handle failure
     ....
   }

Another option is to iteratively check the status of the variable future in a loop, so as to allow the thread to keep doing things:

• A while loop can be defined to keep testing for the response to be ready.

• The method wait_for is used to define the while condition. The function waits for some small amount of time and if no response has been received then it returns std::future_status::timeout which allows you to enter the loop to do whatever you are interested in.

• A global timeout has to be defined to be able not to get stuck forever if no response is received.

The code could be like this:

   auto result = service_client_->async_send_request(request);
   while (result.wait_for(some_amount_of_time) == std::future_status::timeout)
   {
     rclcpp::spin_some(this->get_node_base_interface());

     //do something here like writing a log message before checking again

     // check if the maximum timeout has been elapsed or not. If so, exit the waiting loop
     if ( elapsed > timeout) {
       ...
       break ;
     }
   }
   if (not timed out){//get the result
     auto my_result = result.get();
     ....
   }
   else{ //handle failure
     ....
   }

Exercise

Take a look at the clientasync.cpp file of the foolturtle_server package.

A final option is to use a callback to handle the response:

• The callback is defined by a lambda function.

• The callback will handle the result when ready.

• The thread can continue after the service call, it is not blocked.

   using ServiceResponseFuture =
     rclcpp::Client<foolturtle_server_alone::srv::ChangeVel>::SharedFutureWithRequest;
   //Define a lambda function to handle the response to the service call
   auto response_received_callback =
     [logger = this->get_logger()](ServiceResponseFuture future) {
       auto my_result = future.get();
       .....
     };
   //Service call that includes a callback function to capture the service call response.
   auto result = service_client_->async_send_request(
     request, std::move(response_received_callback));
   //The thread can continue after the call, it is not blocked.

Exercise

Take a look at the clientasync2.cpp file of the foolturtle_server package.

Exercise

Take a look at this example https://github.com/ros2/examples/blob/humble/rclcpp/services/async_client/main.cpp

Exercise

Run the different clients to check how they behave when calling to the change_vel service, which has been coded to add an arbitrary delay in sending the response.

• The sync client gets stuck waiting for the response.

• The async client keeps printing messages while waiting for the response.

• The async2 client just calls the service and continues.

ros2 launch foolturtle_server foolturtle_server_sync_client_launch.py
ros2 launch foolturtle_server foolturtle_server_async_client_launch.py
ros2 launch foolturtle_server foolturtle_server_async2_client_launch.py

Callbacks and Callback Groups

Execution management in ROS 2 is handled by Executors, as discussed in Section Executors. The role of an executor is to check for available work and to execute it. An Executor uses one or more threads of the underlying operating system to invoke the callbacks of subscriptions, timers and services (as seen in previous sections), on incoming messages and events.

Callbacks are part of the code that can be executed only by an executor, or by an invocation of one of the spinning functions (spin, spin once, and spin until future complete).

This section discusses how to correctly manage the callback execution in order to:

• avoid possible deadlocks that may appear because one callback, whose response is needed, cannot be executed because the executor is busy waiting for that response,

• avoid runtime errors that appear if we call functions like spin_some or spin_until_future_complete from within a node that has already been associated with an executor.

The execution of callbacks can be controlled with Callback Groups, which are of two types:

• MutuallyExclusive: the callbacks added to this group cannot be executed simultaneously; this can be used to avoid data-races when accessing shared data without the need of using mutexes.

• Reentrant: callbacks in this kind of group can be executed concurrently by different threads; this can be used to avoid deadlock situations.

By default, a ROS 2 application uses only one MutuallyExclusive callback group, even if associated to a multithreaded executor, which can lead to deadlocks.

To solve this we should create additional callback groups and use a Multithreaded spinner. If the callbacks that need to be executed concurrently or with parallelism are stored in separated groups, or into a group of type “Reentrant”, the spinner will be able to allocate different threads for each of them.

Obviously, the preferred option would be to avoid blocking operations within callbacks, i.e. if the code is written in a way that guarantees that each callback is executed quickly without ever waiting for other callbacks to occur, deadlocks simply won’t occur. But if blocking operations cannot be avoided, the use of Callback Groups is the solution.

As an example the following snippet shows the definition of a Callback Group of time reentrant, and a service that uses it because its callback has a blocking operation.

  //Callback group cb_group_ defined as Reentrant so as to allow the callbacks to be executed concurrently
  //see https://leanpub.com/averyinformaljourneythroughros2 section 3.3
  this->cb_group_ = create_callback_group(rclcpp::CallbackGroupType::Reentrant);

  //Service to control state of the gripper
  GripperOrder_service_ = create_service<test_hardware_package_ros2::srv::GripperOrder>(
     "GripperOrder",
     std::bind(&GripperServerNode::handle_GripperOrder, this, std::placeholders::_1, std::placeholders::_2), rmw_qos_profile_services_default, this->cb_group_);

And the definition of the executor is:

int main(int argc, char *argv[])
{
   rclcpp::init(argc, argv);
   auto node = std::make_shared<GripperServerNode>();

   //Use multithread executor to handle the callback groups
   rclcpp::executors::MultiThreadedExecutor executor;

   executor.add_node(node);
   executor.spin();

   rclcpp::shutdown();
   return 0;
}

Take a look at the following example of the A very informal journey through ROS 2 book, where there is an application with two nodes: the first one starts a timer and, twice per second, asks the second node if it’s alive using a service. The second node simply hosts the is alive service. The code is: https://github.com/nirwester/ros2_journey_examples/tree/master/callbacks_and_executors

EXERCISE 4

To solve Exercise 4 you must modify the urdf_tutorial package you implemented in exercise 3 that you have cloned in your git-projects/exercise4 folder.

Recall to keep commiting the changes when coding the solution (do small commits with good commit messages!) and edit the README.md file in the package explaining your solution (Markdown Cheat Sheet).

Exercise

Modify exercise 3 so as not to broadcast a static grasp transform but to broadcast a dynamic grasp transform set by a service.

1. Implement a urdf_tutorial_interfaces package to define the service with the following SetGraspTransform.srv file:

int32 object_id
geometry_msgs/TransformStamped object_grasp_transform
---
bool ret

2. Implement a node in a file called custom_grasps_tf2_broadcaster.cpp that offers the service called set_grasp_transform to broadcast a transform called ur_grasp to grasp a given object.

3. Implement a client in a file called demo_grasp_client.cpp that:

   1. Calls the service set_grasp_transform to set the following grasp transform between object 12 frame (tf_12) and the ur_grasp frame:

      (x,y,z,R,P,Y)=(0, 0, 0.15, 3.14, 0.0, 0.0)

   2. Calls the inverse kinematics service kinenik_server of package kinenikros2 to compute the joint values to put the robot end effector

   3. Publishes the joint values