rossvcserver

Create ROS service server

Since R2019b

Description

Use rossvcserver or ros.ServiceServer to create a ROS service server that can receive requests from, and send responses to, a ROS service client. You must create the service server before creating the service client rossvcclient.

When you create the service client, it establishes a connection to the server. The connection persists while both client and server exist and can reach each other. When you create the service server, it registers itself with the ROS master. To get a list of services, or to get information about a particular service that is available on the current ROS network, use the rosservice function.

The service has an associated message type and contains a pair of messages: one for the request and one for the response. The service server receives a request, constructs an appropriate response based on a call function, and returns it to the client. The behavior of the service server is inherently asynchronous because it becomes active only when a service client connects to the ROS network and issues a call.

Use the ros.ServiceServer syntax when connecting to a specific ROS node.

Note

In a future release, ROS Toolbox will use message structures instead of objects for ROS messages.

To use message structures now, set the "DataFormat" name-value argument to "struct". For more information, see ROS Message Structures.

Creation

Syntax

server = rossvcserver(servicename,svctype)

server = rossvcserver(servicename,svctype,callback)

[___] = rossvcclient(___,"DataFormat","struct")

server = ros.ServiceServer(node, name,type)

server = ros.ServiceServer(node, name,type,callback)

[___] = ros.ServiceServer(___,"DataFormat","struct")

Description

server = rossvcserver(servicename,svctype) creates a service server object with the specified ServiceType available in the ROS network under the name ServiceName. The service object cannot respond to service requests until you specify a function handle callback, NewMessageFcn.

server = rossvcserver(servicename,svctype,callback) specifies the callback function that constructs a response when the server receives a request. The callback specifies the NewMessageFcn property.

[___] = rossvcclient(___,"DataFormat","struct") uses message structures instead of objects with any of the arguments in previous syntaxes. For more information, see ROS Message Structures.

server = ros.ServiceServer(node, name,type) creates a service server that attaches to the ROS node, node. The server becomes available through the specified service name and type once a callback function handle is specified in NewMessageFcn.

server = ros.ServiceServer(node, name,type,callback) specifies the callback function, which is set to the NewMessageFcn property.

[___] = ros.ServiceServer(___,"DataFormat","struct") uses message structures instead of objects. For more information, see ROS Message Structures.

Properties

ServiceName — Name of the service

string scalar | character vector

This property is read-only.

Name of the service, specified as a string scalar or character vector.

Example: "/gazebo/get_model_state"

Data Types: char | string

ServiceType — Type of service

string scalar | character vector

This property is read-only.

Type of service, specified as a string scalar or character vector.

Example: "gazebo_msgs/GetModelState"

Data Types: char | string

NewMessageFcn — Callback property

function handle | cell array

Callback property, specified as a function handle or cell array. In the first element of the cell array, specify either a function handle, string scalar, or character vector representing a function name. In subsequent elements, specify user data.

The service callback function requires at least three input arguments with one output. The first argument, src, is the associated service server object. The second argument, reqMsg, is the request message object sent by the service client. The third argument is the default response message object, defaultRespMsg. The callback returns a response message, response, based on the input request message and sends it back to the service client. Use the default response message as a starting point for constructing the request message. The function header for the callback is:

function response = serviceCallback(src,reqMsg,defaultRespMsg)

Specify the NewMessageFcn property as:

server.NewMessageFcn = @serviceCallback;

When setting the callback, you pass additional parameters to the callback function by including both the callback function and the parameters as elements of a cell array. The function header for the callback is:

function response = serviceCallback(src,reqMsg,defaultRespMsg,userData)

Specify the NewMessageFcn property as:

server.NewMessageFcn = {@serviceCallback,userData};

DataFormat — Message format

"object" (default) | "struct"

Message format, specified as "object" or "struct". You must set this property on creation using the name-value input. For more information, see ROS Message Structures.

Object Functions

rosmessage

Create ROS messages

Examples

Call Service Client with Default Message

Connect to a ROS network.

rosinit

Launching ROS Core...
Done in 1.0032 seconds.
Initializing ROS master on http://172.30.250.147:60618.
Initializing global node /matlab_global_node_59473 with NodeURI http://dcc277159glnxa64:39507/ and MasterURI http://localhost:60618.

Set up a service server. Use structures for the ROS message data format.

server = rossvcserver('/test', 'std_srvs/Empty', @exampleHelperROSEmptyCallback,...
                      'DataFormat','struct');
client = rossvcclient('/test','DataFormat','struct');

Check whether the service server is available. If it is, wait for the service client to connect to the server.

if(isServerAvailable(client))
    [connectionStatus,connectionStatustext] = waitForServer(client)
end

connectionStatus = logical
   1

connectionStatustext = 
'success'

Call service server with default message.

response = call(client)

response = struct with fields:
    MessageType: 'std_srvs/EmptyResponse'

If the call function above fails, it results in an error. Instead of an error, if you would prefer to react to a call failure using conditionals, return the status and statustext outputs from the call function. The status output indicates if the call succeeded, while statustext provides additional information.

numCallFailures = 0;
[response,status,statustext] = call(client,"Timeout",3);
if ~status
    numCallFailures = numCallFailues + 1;
    fprintf("Call failure number %d. Error cause: %s\n",numCallFailures,statustext)
else
    disp(response)
end

    MessageType: 'std_srvs/EmptyResponse'

Shut down the ROS network.

rosshutdown

Shutting down global node /matlab_global_node_59473 with NodeURI http://dcc277159glnxa64:39507/ and MasterURI http://localhost:60618.
Shutting down ROS master on http://172.30.250.147:60618.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Supported only for struct messages.

• ServiceType argument must be specified.

• Callback functions must be assigned at the time of rossvcserver or ros.ServiceServer object creation, and cannot be changed during run-time.

• For ros.ServiceServer, node input argument must be empty.

• Supported only for the Build Type, Executable.

• Usage in MATLAB Function block is not supported.

Version History

Introduced in R2019b

R2021b: Specify NewMessageFcn call back property when you create the server

In a future release, you must specify the NewMessageFcn callback property during the server creation.

R2021a: ROS Message Structures

You can now create messages as structures with fields matching the message object properties. Using structures typically improves performance of creating, updating, and using ROS messages, but message fields are no longer validated when set. Message types and corresponding field values from the structures are validated when sent across the network.

To use ROS messages as structures, use the "DataFormat" name-value argument when creating your publishers, subscribers, or other ROS objects. Any messages generated from these objects will utilize structures.

pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")
msg = rosmessage(pub)

You can also create messages as structures directly, but make sure to specify the data format as "struct" for the publisher, subscriber, or other ROS objects as well. ROS objects still use message objects by default.

msg = rosmessage("/scan","sensor_msgs/LaserScan","DataFormat","struct")
...
pub = rospublisher("/scan","sensor_msgs/LaserScan","DataFormat","struct")

In a future release, ROS messages will use structures by default and ROS message objects will be removed.

For more information, see Improve Performance of ROS Using Message Structures.