rosActionServerExecuteGoalFcn

Return function handle for ROS action server callback

Since R2022a

Syntax

cb = rosActionServerExecuteGoalFcn

cb = rosActionServerExecuteGoalFcn(Name=Value)

Description

rosActionServerExecuteGoalFcn provides a predefined callback framework for use as the goal execution callback in a ROS action server. The callback framework is a set of callback functions, one for each of these tasks the server must carry out during goal execution:

• Check if the goal is reached

• Execute items in every iteration towards the goal

• Construct feedback message for the action client

• Construct result message if the goal is preempted

• Construct result message if the goal is reached successfully

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

cb = rosActionServerExecuteGoalFcn returns a function handle, cb, with a predefined callback framework for action server goal execution. You can specify cb as value for the ExecuteGoalFcn name-value argument when you create the rosactionserver object. When you use the function handle from this syntax in the action server, the callback immediately indicates that the goal has been reached and returns the default result message.

cb = rosActionServerExecuteGoalFcn(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. The custom functions must have two input arguments: a shared object containing UserData as the first, and an appropriate ROS message as the second. Most functions must also provide appropriate output. For more information about each function signature, see Name-Value Arguments.

Examples

Create Custom Callback for a ROS Action Server Using the Predefined Callback Framework

This example shows how to create a custom callback for a ROS action server using rosActionServerExecuteGoalFcn, which provides a customizable predefined callback framework.

Connect to a ROS network.

rosinit

Launching ROS Core...
Done in 0.71716 seconds.
Initializing ROS master on http://172.30.181.117:55096.
Initializing global node /matlab_global_node_79265 with NodeURI http://dcc271787glnxa64:44587/ and MasterURI http://localhost:55096.

Set up an action server callback for calculating the Fibonacci sequence using rosActionServerExecuteGoalFcn. Specify the custom callback functions for the tasks in the callback framework. All the callback functions use a shared object to store data. For definition of these custom functions, see Supporting Functions.

% Store the first two terms 0 and 1 in shared object
fibSequence = int32([0 1]);
% Create the callback
cb = rosActionServerExecuteGoalFcn(IsGoalReachedFcn=@isGoalReached,...
        StepExecutionFcn=@nextFibNumber,...
        CreateFeedbackFcn=@assignUserDataToMessage,...
        CreateSuccessfulResultFcn=@assignUserDataToMessage,...
        StepDelay=0.2,...
        UserData=fibSequence);

Use the created custom callback, cb and set up an action server for calculating Fibonacci sequence. Use structures for the ROS message data format.

server = rosactionserver("/fibonacci","actionlib_tutorials/Fibonacci",ExecuteGoalFcn=cb,DataFormat="struct");

Create action client and send a goal to the server, which calculates the first 10 terms in the Fibonacci sequence. Display the result sequence.

client = rosactionclient("/fibonacci","actionlib_tutorials/Fibonacci",DataFormat="struct");
goal = rosmessage(client);
goal.Order = int32(10);
result = sendGoalAndWait(client,goal);
result.Sequence

ans = 10x1 int32 column vector

    0
    1
    1
    2
    3
    5
    8
   13
   21
   34

Shut down ROS network.

rosshutdown

Shutting down global node /matlab_global_node_79265 with NodeURI http://dcc271787glnxa64:44587/ and MasterURI http://localhost:55096.
Shutting down ROS master on http://172.30.181.117:55096.

Supporting Functions

The function isGoalReached checks whether the goal is reached. In this case, it checks whether the number of terms in the calculated Fibonacci sequence exceeds the goal from the client.

function status = isGoalReached(sharedObj,goal) 
    status = numel(sharedObj.UserData) >= goal.Order;
end

The function nextFibNumber is the step execution function that calculates the next term in the sequence in every iteration towards goal execution.

function nextFibNumber(sharedObj,~)
    sharedObj.UserData(end+1) = sharedObj.UserData(end-1) + sharedObj.UserData(end);
end

The function assignUserDataToMessage assigns the current sequence to the appropriate field in the result message. In this specific case of Fibonacci action, the feedback message also uses the same field, Sequence as the result message. Hence, this function can be used for both creating a feedback message and result message to the client.

function msg = assignUserDataToMessage(sharedObj,msg)
    msg.Sequence = sharedObj.UserData;
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.

Example: StepDelay=0.01

IsGoalReachedFcn — Callback function to determine if goal is reached

function handle

Callback function to determine if the goal is reached, specified as a function handle. In the default framework, this function always returns true. When specifying the handle for a custom function, the function must have two input arguments: a shared object containing UserData as the first, and the goal message as the second. This is an example function header signature:

function atGoal = isGoalReached(sharedObj,goalMsg)

You can use the data or resources in sharedObj.UserData to check the current state, determine whether the goal is reached, and return true or false appropriately.

Example: @isGoalReached

Data Types: function_handle

StepExecutionFcn — Callback function to progress toward goal each iteration

empty (default) | function handle

Callback function to progress toward the goal each iteration, specified as a function handle. In the default framework, StepExecutionFcn is empty, and no step function will be executed. When specifying the handle for a custom function, the function must have two input arguments: a shared object containing UserData as the first, and the goal message as the second. This is an example function header signature:

function stepExecution(sharedObj,goalMsg)

You can use the data or resources in sharedObj.UserData as required to progress towards the goal.

Example: @stepExecution

Data Types: function_handle

CreateFeedbackFcn — Callback function to construct feedback message each iteration

empty (default) | function handle

Callback function to construct a feedback message each iteration for the action client, specified as a function handle. In the default framework, CreateFeedbackFcn is empty and no feedback will be sent to the client. When specifying the handle for a custom function, the function must have two input arguments: a shared object containing UserData as the first, and the goal message as the second. This is an example function header signature:

function feedback = createFeedback(sharedObj,defaultFeedbackMsg)

You can use the data or resources in sharedObj.UserData as required to construct the feedback message to send to the action client.

Example: @createFeedback

Data Types: function_handle

CreatePreemptedResultFcn — Callback function to construct result message if goal is preempted

function handle

Callback function to construct the result message if the goal is preempted, specified as a function handle. The result message is then sent to the action client. In the default framework, this function always returns the default result message. When specifying the handle for a custom function, the function must have two input arguments: a shared object containing UserData as the first, and the goal message as the second. This is an example function header signature:

function result = createPreemptedResult(sharedObj,defaultResultMsg)

You can use the data or resources in sharedObj.UserData as required to construct the result message reflecting the incomplete goal execution.

Example: @createPreemptedResult

Data Types: function_handle

CreateSuccessfulResultFcn — Callback function to construct result message if goal is reached successfully

function handle

Callback function to construct the result message if the goal is reached successfully, specified as a function handle. The result message is then sent to the action client. In the default framework, this function always returns the default result message. When specifying the handle for a custom function, the function must have two input arguments: a shared object containing UserData as the first, and the goal message as the second. This is an example function header signature:

function result = createSuccessfulResult(sharedObj,defaultResultMsg)

You can use the data or resources in sharedObj.UserData as required to construct the result message that reflects successful goal execution.

Example: @createSuccessfulResult

Data Types: function_handle

StepDelay — Number of seconds to pause each iteration

0.01 seconds (default) | nonnegative scalar

Number of seconds to pause each iteration, specified as a nonnegative scalar. Provide a nonzero value to allow:

• Execution of other callbacks

• ROS action client to react to the received feedback

Example: 0.1

UserData — Data for use and modification during goal execution shared by all callbacks

[] (default) | scalar | array | structure

Data for use and modification during goal execution shared by all callbacks, specified as a scalar, array, or a structure. This data is stored in an object passed to all the callbacks in the framework. This enables all tasks to share the same data during goal execution, and any modifications made during one task are reflected in subsequent tasks.

Example: eye(3)

Output Arguments

cb — Callback function

function handle

Callback for use as the goal execution callback in a ROS action server, returned as a function handle. You can specify cb as the value of the ExecuteGoalFcn name-value argument when you create a rosactionserver object.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• The UserData specified for the callback created using rosActionServerExecuteGoalFcn function must be a 1-D array.

Version History

Introduced in R2022a