ros2ActionSendGoalOptions

Return structure for ROS 2 action client callback

Since R2023a

Syntax

cb = ros2ActionSendGoalOptions

cb = ros2ActionSendGoalOptions(Name=Value)

Description

ros2ActionSendGoalOptions provides a predefined callback framework for use as the send goal callback for ROS 2 action client. The callback framework is a set of callback functions, consisting of the tasks the action client must carry out based on these responses from the action server:

• Goal Response

• Feedback Response

• Result message

You can specify custom functions for these tasks by using the respective name-value arguments of ros2ActionSendGoalOptions.

cb = ros2ActionSendGoalOptions returns a callback options structure cb, with a predefined callback framework for action client to send goals. You can specify cb as value for the callbackOptions input argument when you send goals using the sendGoal function. When you use the function handle from this syntax to send goal, cb specifies a goal response callback to indicate that the goal has been accepted by the server immediately.

cb = ros2ActionSendGoalOptions(Name=Value) specifies additional options using one or more name-value arguments. To customize the behavior of the predefined callback framework, specify handles of custom functions using the corresponding name-value arguments. All custom functions must have the ros2ActionGoalHandle object associated with the goal as an input argument. Some functions have additional input arguments that you must specify. For more information about each function signature, see Name-Value Arguments.

Examples

Set Up ROS 2 Action Client and Execute an Action

This example shows how to create a ROS 2 action client and execute the action. 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

List the actions available on the network. The /fibonacci action must be on the list.

ros2 action list

/fibonacci

Get the action type for the /fibonacci action.

ros2 action type /fibonacci

action_tutorials_interfaces/Fibonacci

Create a ROS 2 node.

node = ros2node("/node_1");

Create an action client by specifying the node, action name, and action type. Set the quality of service (QoS) parameters.

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

Wait for the action client to connect to the server.

status = waitForServer(client)

status = logical
   1

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. If the input requires a 1-D array, set it as a column vector.

goalMsg.order = int32(8);

Send Goal and Execute Action

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 and the final result using the name-value arguments.

callbackOpts = ros2ActionSendGoalOptions(FeedbackFcn=@helperFeedbackCallback,ResultFcn=@helperResultCallback);

Send the goal to the action server using the sendGoal function. Specify the callback options. During goal execution, you see outputs from the feedback and result callbacks displayed on the MATLAB® command window.

goalHandle = sendGoal(client,goalMsg,callbackOpts);

Goal with GoalUUID 3d10ab880f960666fde5666f45f621a accepted by server, waiting for result!
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0  1  1
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0  1  1  2
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0  1  1  2  3
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0  1  1  2  3  5
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0  1  1  2  3  5  8
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0   1   1   2   3   5   8  13
Partial sequence feedback for goal 3d10ab880f960666fde5666f45f621a is 0   1   1   2   3   5   8  13  21
Full sequence result for goal 3d10ab880f960666fde5666f45f621a is 0   1   1   2   3   5   8  13  21

Get the status of goal execution.

exStatus = getStatus(client,goalHandle)

exStatus = int8
    2

Get the result using the action client and goal handle inputs. Display the result. The getResult function returns the sequence as a column vector.

resultMsg = getResult(client,goalHandle);
rosShowDetails(resultMsg)

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

Alternatively, you can only use the goal handle as input to get the result.

resultMsg = getResult(goalHandle);
rosShowDetails(resultMsg)

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

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

helperResultCallback defines the callback function to execute when the client receives the result message from the action server.

function helperResultCallback(goalHandle,wrappedResultMsg)
    seq = wrappedResultMsg.result.sequence;
    disp(['Full sequence result for goal ',goalHandle.GoalUUID,' is ',num2str(seq')])
end

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

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: GoalRespFcn=@glResponse

GoalRespFcn — Callback function called after receiving goal response from the server

function handle

Callback function called after receiving goal response from the server, specified as a function handle. In the default framework, this function specifies a callback to indicate that the goal has been accepted by the server immediately. When specifying the handle for a custom function, the function must have the ros2ActionGoalHandle object associated with the goal as the first input argument. This is an example function header signature:

function goalRespFcn(goalHandle,varargin)

You can provide additional data to the callback using multiple subsequent input arguments. This is indicated by the varargin variable.

Example: @glResponse

Data Types: function_handle

FeedbackFcn — Callback function called when receiving feedback response from the server

function handle

Callback function called when receiving feedback response from the server, specified as a function handle. In the default framework, this function specifies a callback to indicate that the goal has been accepted by the server immediately. When specifying the handle for a custom function, the function must have two input arguments: a ros2ActionGoalHandle object associated with the goal as the first, and the received feedback message as the second. This is an example function header signature:

function feedbackFcn(goalHandle,fbMsg,varargin)

You can provide additional data to the callback using multiple subsequent input arguments. This is indicated by the varargin variable.

Example: @glFeedback

Data Types: function_handle

ResultFcn — Callback function called when receiving result message from the server

function handle

Callback function called when receiving result message from the server, specified as a function handle. In the default framework, this function specifies a callback to indicate that the goal has been accepted by the server immediately. When specifying the handle for a custom function, the function must have two input arguments: a ros2ActionGoalHandle object associated with the goal as the first, and the received wrapped result message as the second. The wrapped result message contains these fields:

• result — Received result message

• code — Received result code

• goalUUID — Unique index of the goal associated with the result

This is an example function header signature:

function resultFcn(goalHandle,wrappedResultMsg,varargin)

You can provide additional data to the callback using multiple subsequent input arguments. This is indicated by the varargin variable.

Example: @glResult

Data Types: function_handle

Note

To supply additional data to callback functions, you can specify one additional input argument. You must include both the callback function and the additional input argument as elements of a cell array while defining the call back options using ros2ActionSendGoalOptions. For example:

cb = ros2ActionSendGoalOptions(FeedbackFcn={@glFeedback,2.5},ResultFcn={@glResult,5.0});

Output Arguments

cb — Callback options framework

structure

Callback options framework, returned as a structure. The fields of the structure specify the function handles for goal response, feedback and result callbacks along with the required data for each of the callbacks. You can use cb as value for the callbackOptions input argument when you send a goal using the sendGoal function.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• When you create callback options to send goals using the ros2ActionSendGoalOptions function, any additional input arguments to GoalRespFcn, FeedbackFcn and ResultFcn callbacks are not supported. Only function signature with the goal handle and/or received message as input arguments is supported.

Version History

Introduced in R2023a