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.

Use the sendFeedback function to send feedback messages to the client during goal execution. During goal execution, the server calls the ExecuteGoalFcn callback. You can use isPreemeptRequested within the callback function to check whether the client has cancelled the goal or sent a new goal to execute.

Performing Actions Workflow

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

• To set up a ROS action server, use rosactionserver. 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')

• FeedbackMsg — The feedback message contains information sent to the client by the server during goal execution. The type of feedback message depends on the action type. This feedback contains the current state and any other information related to the progress towards goal execution. Use sendFeedback function to send the feedback message from the server.

• 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 rosShowDetails. You can do other processing on the feedback message in the feedback function.

  The default function handle is:

  @(~,msg) disp(['Feedback: ',rosShowDetails(msg)])

  msg is the feedback message as an input argument to the function you define.

• ResultMsg — The server sends the final result message to the client after goal execution as the output argument to sendGoal or sendGoalAndWait.

• 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)])