ROS Actions Overview

Client to Server Relationship

ROS Actions have a client-to-server communication relationship with a specified protocol. The actions use ROS topics to send goal messages from a client to the server. You can cancel goals using the action client. After receiving a goal, the server processes it and can give information back to the client. This information includes the status of the server, the state of the current goal, feedback on that goal during operation, and finally a result message when the goal is complete.

Use the sendGoal function to send goals to the server. Send the goal and wait for it to complete using sendGoalAndWait. This function enables you to return the result message, final state of the goal and status of the server. While the server is executing a goal, the callback function, FeedbackFcn, is called to provide data relevant to that goal (see SimpleActionClient). Cancel the current goal using cancelGoal or all goals on server using cancelAllGoals.

Performing Actions Workflow

In general, the following steps occur when creating and executing a ROS action on a ROS network.

Setup ROS action server. Check what actions are available on a ROS network by typing rosaction list in the MATLAB^® command window.
Use rosactionclient to create action clients and connect them to the server. Specify an action type currently available on the ROS network. Use waitForServer to wait for the action client to connect to the server.
Send a goal using sendGoal. Define a goalMsg that corresponds to the action type. When you create an action client using rosactionclient, a blank goalMsg is returned. You can modify this message with your desired parameters.
When a goal status becomes 'active', the goal begins execution and the ActivationFcn callback function is called. For more information on modifying this callback function, see SimpleActionClient.
While the goal status remains 'active', the server continues to execute the goal. The feedback callback function processes information about this goals execution periodically whenever a new feedback message is received. Use the FeedbackFcn to access or process the message data sent from the ROS server.
When the goal is achieved, the server returns a result message and status. Use the ResultFcn callback to access or process the result message and status.

Action Messages and Functions

ROS actions use ROS messages to send goals and receive feedback about their execution. In MATLAB, you can use callback functions to access or process the feedback and result information from these messages. After you create the SimpleActionClient object, specify the callback functions by assigning function handles to the properties on the object. You can create the object using rosactionclient.

GoalMsg — The goal message contains information about the goal. To perform an action, you must send a goal message with updated goal information (see sendGoal). The type of goal message depends on the type of ROS action.
ActivationFcn — Once a goal is received on the action server, its status goes to 'pending' until the server decides to execute it. The status is then 'active'. At this moment, MATLAB executes the callback function defined in the ActivationFcn property of the SimpleActionClient object. There is no ROS message or data associated with this function. By default, this function simply displays 'Goal is active' on the MATLAB command line to notify you the goal is being executed.
The default function handle is:
```
@(~) disp('Goal is active')
```
FeedbackFcn — The feedback function is used to process the information from the feedback message. The type of feedback message depends on the action type. The feedback function executes periodically during the goal operation whenever a new feedback message is received. By default, the function displays the details of the message using showdetails. You can do other processing on the feedback message in the feedback function.
The default function handle is:
```
@(~,msg) disp(['Feedback: ',showdetails(msg)])
```
msg is the feedback message as an input argument to the function you define.
ResultFcn — The result function executes when the goal has been completed. Inputs to this function include both the result message and the status of execution. The type of result message depends on the action type. This message, msg, and status, s, are the same as the outputs you get when using sendGoalAndWait. This function can also be used to trigger dependent processes after a goal is completed.
The default function handle is:
```
@(~,s,msg) disp(['Result with state ',char(s),': ',showdetails(msg)])
```

Documentation