getResult

Get result of specific goal associated with goal handle

Since R2023a

Syntax

resultMsg = getResult(client,goalHandle)

resultMsg = getResult(goalHandle)

resultMsg = getResult(___,Timeout=timeoutperiod)

[resultMsg,status,statustext] = getResult(___)

Description

resultMsg = getResult(client,goalHandle) returns the result message resultMsg associated with the execution of the goal specified by goalHandle. The goal must be sent by the action client client. This syntax blocks MATLAB^® from running the current program until the action server provides resultMsg. You can Press Ctrl+C to cancel the wait.

resultMsg = getResult(goalHandle) returns the result message resultMsg associated with the execution of the goal specified by goalHandle. This syntax blocks MATLAB from running the current program until the action server provides resultMsg. You can Press Ctrl+C to cancel the wait.

resultMsg = getResult(___,Timeout=timeoutperiod) specifies a timeout period in seconds using the name-value argument Timeout=timeoutperiod. If the action server does not return the result message 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.

[resultMsg,status,statustext] = getResult(___) returns a status indicating whether the action client received the result message, and a statustext that captures additional information about the status, using any of the arguments from the previous syntaxes. If the action server does not return the result message within the Timeout, status will be false, and this function will not display an error.

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

Input Arguments

client — ROS 2 action client

ros2actionclient object handle

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

goalHandle — Action client goal handle

ActionClientGoalHandle object

Action client goal handle, specified as an ActionClientGoalHandle object.

Output Arguments

resultMsg — Result message received from the action server

structure

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

status — Status of the result message receipt

logical scalar

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

Note

Use the status output argument when you use getResult 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 result message receipt

character vector

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

• 'unknown' — Result message receipt failed for unknown reason.

• 'succeeded' — The result message was successfully received.

• 'failed' — Result message receipt failed because the goal was canceled.

• 'aborted' — Result message receipt failed because the goal was aborted.

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

• 'timeout' — The result message 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