cancelAllGoalsAndWait

Cancel all active goals sent by ROS 2 action client and wait for cancel response

Since R2023a

Syntax

cancelResponse = cancelAllGoalsAndWait(client)

cancelResponse = cancelAllGoalsAndWait(client,Timeout=timeoutperiod)

[cancelResponse,status,statustext] = cancelAllGoalsAndWait(___)

Description

cancelResponse = cancelAllGoalsAndWait(client) sends a cancel request for all the active goals sent by the ROS 2 action client, client. This syntax blocks MATLAB^® from running the current program until the action server returns the cancel response cancelResponse. Press Ctrl+C to cancel the wait.

cancelResponse = cancelAllGoalsAndWait(client,Timeout=timeoutperiod) specifies a timeout period in seconds using the name-value argument Timeout=timeoutperiod. If the action server does not return the cancel response in the timeout period, this function displays an error and lets MATLAB continue running the current program. The default value of inf prevents MATLAB from running the current program until the action client receives a cancel response.

[cancelResponse,status,statustext] = cancelAllGoalsAndWait(___) returns a status indicating whether the action client received the cancel response, and a statustext that captures additional information about the status, using any of the arguments from the previous syntaxes. If the server is not available within the Timeout, status will be false, and this function will not display an error.

Examples

Send and Cancel ROS 2 Action Goals

This example shows how to send and cancel ROS 2 action goals. Action types must be set up beforehand with an action server running. This example uses the /fibonacci action. Follow these steps to set up the action server:

1. Create a ROS 2 package with the action definition. For instructions on setting up a /fibonacci action, see Creating an Action.

2. Create a ROS 2 package with the action server implementation. For more information on setting up the /fibonacci action server, see Writing an Action Server.

3. Use the ros2genmsg function for the ROS 2 package with action definition from Step 1, and generate action messages in MATLAB®.

To run the /fibonacci action server, use this command on the ROS 2 system:

ros2 run action_tutorials_cpp fibonacci_action_server

Set Up ROS 2 Action Client

Create a ROS 2 node.

node = ros2node("/node_1");

Create an action client for /fibonacci action by specifying the node, action name, and action type. Set the quality of service (QoS) parameters.Wait for the action client to connect to the server.

[client,goalMsg] = ros2actionclient(node,"fibonacci",...
"action_tutorials_interfaces/Fibonacci", ...
CancelServiceQoS=struct(Depth=200,History="keeplast"), ...
FeedbackTopicQoS=struct(Depth=200,History="keepall"));
status = waitForServer(client)

status = logical
   1

Before sending the goal, define the callback options framework for the goal execution process. In this example, you specify a callback function to execute when the server returns a feedback response.

callbackOpts = ros2ActionSendGoalOptions(FeedbackFcn=@helperFeedbackCallback);

Send and Cancel Goals

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);

Create a new goal message and set the order to an int32 value of 10.

goalMsg2 = ros2message(client);
goalMsg2.order = int32(10);

Send both the goals to the action server using the sendGoal function. Specify the same callback options for both goals.

goalHandle = sendGoal(client,goalMsg,callbackOpts);
goalHandle2 = sendGoal(client,goalMsg2,callbackOpts);

Goal with GoalUUID ca8dbca2b8608a6f2add01b298f6930 accepted by server, waiting for result!
Partial sequence feedback for goal ca8dbca2b8608a6f2add01b298f6930 is 0  1  1
Goal with GoalUUID f493913f4acd2224f31145ae74bbc35 accepted by server, waiting for result!
Partial sequence feedback for goal f493913f4acd2224f31145ae74bbc35 is 0  1  1

Cancel the specific goal associated with the sequence order 8. Use the goal handle object associated with that goal as input to the cancelGoal function, and specify the cancel callback to execute once the client receives the cancel response. This function returns immediately without waiting for the cancel response to arrive.

cancelGoal(client,goalHandle,CancelFcn=@helperCancelGoalCallback)

Goal ca8dbca2b8608a6f2add01b298f6930 is cancelled with return code 0

You can wait until the cancel response arrives from the server by using the cancelGoalAndWait function. Cancel the goal associated with the sequence order of 10 and wait until the client receives the cancel response.

cancelResponse = cancelGoalAndWait(client,goalHandle2)

cancelResponse = struct with fields:
              MessageType: 'action_msgs/CancelGoalResponse'
               ERROR_NONE: 0
           ERROR_REJECTED: 1
    ERROR_UNKNOWN_GOAL_ID: 2
    ERROR_GOAL_TERMINATED: 3
              return_code: 0
          goals_canceling: [1×1 struct]

Cancel Goals Before Timestamp

Send the goal message with sequence order 10. Note the timestamp in a ROS 2 message by using the ros2time function.

goalHandle = sendGoal(client,goalMsg2,callbackOpts);
timeStampMsg = ros2time(node,"now");

Goal with GoalUUID d8268c566b234e8784f0f1a8ec12b2 accepted by server, waiting for result!
Partial sequence feedback for goal d8268c566b234e8784f0f1a8ec12b2 is 0  1  1

Then, send a second goal message with sequence order 8. Note the timestamp.

goalHandle2 = sendGoal(client,goalMsg,callbackOpts);
timeStampMsg2 = ros2time(node,"now");

Goal with GoalUUID 9585bff2ba44bf60daa630a952b458be accepted by server, waiting for result!
Partial sequence feedback for goal 9585bff2ba44bf60daa630a952b458be is 0  1  1

Cancel the goal sent before the first time stamp using cancelGoalsBefore function.

cancelGoalsBefore(client,timeStampMsg,CancelFcn=@helperCancelGoalsCallback)

Goals cancelled with return code 0

Use the cancelGoalsBeforeAndWait function to cancel the goal sent before second time stamp and wait for the cancel response.

cancelResponse = cancelGoalsBeforeAndWait(client,timeStampMsg2)

cancelResponse = struct with fields:
              MessageType: 'action_msgs/CancelGoalResponse'
               ERROR_NONE: 0
           ERROR_REJECTED: 1
    ERROR_UNKNOWN_GOAL_ID: 2
    ERROR_GOAL_TERMINATED: 3
              return_code: 0
          goals_canceling: [1×1 struct]

Cancel All Goals

Cancel all the active goals that the client sent.

goalHandle = sendGoal(client,goalMsg,callbackOpts);
cancelAllGoals(client,CancelFcn=@helperCancelGoalsCallback);

Goals cancelled with return code 0

Cancel all the active goals that the client sent and wait for cancel response.

goalHandle2 = sendGoal(client,goalMsg2,callbackOpts);
cancelResponse = cancelAllGoalsAndWait(client)

cancelResponse = struct with fields:
              MessageType: 'action_msgs/CancelGoalResponse'
               ERROR_NONE: 0
           ERROR_REJECTED: 1
    ERROR_UNKNOWN_GOAL_ID: 2
    ERROR_GOAL_TERMINATED: 3
              return_code: 0
          goals_canceling: [1×1 struct]

Helper Functions

helperFeedbackCallback defines the callback function to execute when the client receives a feedback response from the action server.

function helperFeedbackCallback(goalHandle,feedbackMsg)
seq = feedbackMsg.partial_sequence;
disp(['Partial sequence feedback for goal ',goalHandle.GoalUUID,' is ',num2str(seq')])
end

helperCancelGoalCallback defines the callback function to execute when the client receives a cancel response after canceling a specific goal.

function helperCancelGoalCallback(goalHandle,cancelMsg)
code = cancelMsg.return_code;
disp(['Goal ',goalHandle.GoalUUID,' is cancelled with return code ',num2str(code)])
end

helperCancelGoalsCallback defines the callback function to execute when the client receives a cancel response after canceling a set of goals.

function helperCancelGoalsCallback(cancelMsg)
code = cancelMsg.return_code;
disp(['Goals cancelled with return code ',num2str(code)])
end

Input Arguments

client — ROS 2 action client

ros2actionclient object handle

ROS 2 action client, specified as a ros2actionclient object handle.

Output Arguments

cancelResponse — Cancel response received from the action server

structure

Cancel response received from the action server, returned as a ROS 2 message structure.

status — Status of the cancel response receipt

logical scalar

Status of the cancel response receipt, returned as a logical scalar. If the action client does not receive a cancel response within the timeout period, status will be false.

Note

Use the status output argument when you use cancelAllGoalsAndWait for code generation. This will avoid runtime errors and outputs the status instead, which can be reacted to in the calling code.

statustext — Status text associated with the cancel response receipt

character vector

Status text associated with the cancel response receipt, returned as one of the following:

• 'success' — The cancel response was successfully received.

• 'input' — The input to the function is invalid.

• 'timeout' — The cancel response was not received before the timeout period expired.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2023a