Explore ROS Actions: Action Client and Action Server Guide

Action is another communication mechanism meant for long-running tasks. Actions are comprised of two components: the action client and the action server.

• Client –– An action client is a node which requests a goal to be completed on its behalf. It waits for feedbacks and a result upon completion.

• Server –– An action server is a node which accepts the goal, and performs the procedures required. It sends out feedback as the action progresses and returns a full result when the goal is achieved.

Action Interface

Action messages are described in a .action file. Actions are used for long-running tasks, where a client node sends a goal to a server node, which provides feedback on the task's progress and sends a result upon completion. Hence, an action file comprises of three parts/messages: a goal, feedback, and a result.

You can view the list of available action message types by using rosmsg list.

rosmsg list

actionlib/TestAction                                           
actionlib/TestActionFeedback                                   
actionlib/TestActionGoal                                       
actionlib/TestActionResult                                     
actionlib/TestFeedback                                         
actionlib/TestGoal                                             
actionlib/TestRequestAction                                    
actionlib/TestRequestActionFeedback                            
actionlib/TestRequestActionGoal                                
actionlib/TestRequestActionResult
actionlib_tutorials/FibonacciFeedback                          
actionlib_tutorials/FibonacciGoal                              
actionlib_tutorials/FibonacciResult...

This list contains action message types of predefined message interface definitions. You can create a message of any of these predefined types such as roscpp_tutorials/TwoInts.

Send Action Goal, Monitor Feedback and Receive Result

Create ROS Action Server and Execute Goal

This example shows how to create a ROS action server, connect an action client to it, receive goal, and execute it.

Connect to a ROS network.

rosinit

Launching ROS Core...
..Done in 2.1278 seconds.
Initializing ROS master on http://172.19.136.75:52554.
Initializing global node /matlab_global_node_56708 with NodeURI http://vdi-wd1bgl-223:61999/ and MasterURI http://localhost:52554.

Set up an action server for calculating Fibonacci sequence. Use structures for the ROS message data format. Use fibbonacciExecution function as the callback.

cb = @fibonacciExecution; 
server = rosactionserver("/fibonacci","actionlib_tutorials/Fibonacci",ExecuteGoalFcn=cb,DataFormat="struct")

server = 
  SimpleActionServer with properties:

        ActionName: '/fibonacci'
        ActionType: 'actionlib_tutorials/Fibonacci'
    ExecuteGoalFcn: @fibonacciExecution
        DataFormat: 'struct'

Create action client and send a goal to the server to calculate the Fibonacci sequence up to 10 terms past the first two terms, 0 and 1. Display the result sequence.

client = rosactionclient("/fibonacci","actionlib_tutorials/Fibonacci",DataFormat="struct");
goal = rosmessage(client);
goal.Order = int32(10);
result = sendGoalAndWait(client,goal);
result.Sequence

ans = 12×1 int32 column vector

    0
    1
    1
    2
    3
    5
    8
   13
   21
   34
      ⋮

Shut down ROS network.

rosshutdown;

Shutting down global node /matlab_global_node_56708 with NodeURI http://vdi-wd1bgl-223:61999/ and MasterURI http://localhost:52554.
Shutting down ROS master on http://172.19.136.75:52554.

Warning: Error shutting down the ROS master.

Supporting Functions

The callback function fibbonacciExecution is executed every time the server receives a goal execution request from the client. This function checks if the goal has been preempted, executes the goal and sends feedback to the client during goal execution.

function [result,success] = fibonacciExecution(src,goal,defaultFeedback,defaultResult)

    % Initialize variables
    success = true;
    result = defaultResult;
    feedback = defaultFeedback;
    feedback.Sequence = int32([0 1]);

    for k = 1:goal.Order
        % Check that the client has not canceled or sent a new goal
        if isPreemptRequested(src)
            success = false;
            break
        end

        % Send feedback to the client periodically
        feedback.Sequence(end+1) = feedback.Sequence(end-1) + feedback.Sequence(end);
        sendFeedback(src,feedback)
        
        % Pause to allow time to complete other callbacks (like client feedback)
        pause(0.2)
    end

    if success
        result.Sequence = feedback.Sequence;
    end

end

Set Up ROS Action Client and Execute Action

This example shows how to create a ROS action client and execute the action. Action types must be set up beforehand with an action server running.

You must have set up the '/fibonacci' action type. To run this action server, use the following command on the ROS system:

rosrun actionlib_tutorials fibonacci_server

Connect to a ROS network. You must be connected to a ROS network to gather information about what actions are available. Replace ipaddress with your network address.

ipaddress = '192.168.203.133';
rosinit(ipaddress,11311)

Initializing global node /matlab_global_node_81947 with NodeURI http://192.168.203.1:54283/

List actions available on the network. The only action set up on this network is the '/fibonacci' action.

rosaction list

/fibonacci

Create an action client by specifying the action name. Use structures for ROS messages.

[actClient,goalMsg] = rosactionclient('/fibonacci','DataFormat','struct');

Wait for the action client to connect to the server.

waitForServer(actClient);

The fibonacci action will calculate the fibonacci sequence for a given order specified in the goal message. The goal message was returned when creating the action client and can be modified to send goals to the ROS action server. Set the order to an int32 value of 8.

goalMsg.Order = int32(8);

Send the goal and wait for its completion. Specify a timeout of 10 seconds to complete the action.

[resultMsg,resultState] = sendGoalAndWait(actClient,goalMsg,10);

rosShowDetails(resultMsg)

ans = 
    '
       MessageType :  actionlib_tutorials/FibonacciResult
       Sequence    :  [0, 1, 1, 2, 3, 5, 8, 13, 21]'

Disconnect from the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_81947 with NodeURI http://192.168.203.1:54283/

Send and Cancel ROS Action Goals

This example shows how to send and cancel goals for ROS actions. Action types must be setup beforehand with an action server running.

You must have set up the '/fibonacci' action type. To run this action server, use the following command on the ROS system:

rosrun actionlib_tutorials fibonacci_server

First, set up a ROS action client. Then, send a goal message with modified parameters. Finally, cancel your goal and all goals on the action server.

Connect to a ROS network with a specified IP address. Create a ROS action client connected to the ROS network using rosactionclient. Specify the action name. Wait for the client to be connected to the server.

rosinit('192.168.203.133',11311)

Initializing global node /matlab_global_node_18287 with NodeURI http://192.168.203.1:55284/

[actClient,goalMsg] = rosactionclient('/fibonacci','DataFormat','struct');
waitForServer(actClient);

Send a goal message with modified parameters. Wait for the goal to finish executing.

goalMsg.Order = int32(4);
[resultMsg,resultState] = sendGoalAndWait(actClient,goalMsg)

resultMsg = struct with fields:
    MessageType: 'actionlib_tutorials/FibonacciResult'
       Sequence: [0 1 1 2 3]

resultState = 
'succeeded'

rosShowDetails(resultMsg)

ans = 
    '
       MessageType :  actionlib_tutorials/FibonacciResult
       Sequence    :  [0, 1, 1, 2, 3]'

Send a new goal message without waiting.

goalMsg.Order = int32(5);
sendGoal(actClient,goalMsg)

Cancel the goal on the ROS action client, actClient.

cancelGoal(actClient)

Cancel all the goals on the action server that actClient is connected to.

cancelAllGoals(actClient)

Delete the action client.

delete(actClient)

Disconnect from the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_18287 with NodeURI http://192.168.203.1:55284/

Custom Message Support for ROS Actions

While leveraging standard action interfaces proves useful, there are scenarios where creating custom ROS action messages becomes essential to meet specific needs within your robotic applications. For instance, if you need to broaden the functionality of generating Fibonacci sequences to cover real and complex numbers, ROS enables you to define custom actions in your packages. The ROS Toolbox extends support for generating custom ROS action messages, detailed in ROS Custom Message Support.

To generate ROS custom messages, you can use the rosgenmsg function to read ROS custom message definitions in the specified folder path. The designated folder should contain one or more ROS packages containing action message definitions in .action files. Additionally, you can create a shareable ZIP archive of the generated custom messages. This archive facilitates registering the custom messages on another machine using rosRegisterMessages.

In MATLAB^®, you typically don't write .action files directly. Instead, you create custom messages using ROS package tools and then use them in MATLAB.