Main Content

ros2svcclient

Connect to ROS 2 service server

Since R2021b

expand all in page

Description

Use ros2svcclient to create a ROS 2 service client object. This service client uses a connection to send requests to, and receive responses from, a ROS 2 service server. For more information, see Call and Provide ROS 2 Services.

Creation

Syntax

client = ros2svcclient(node,servicename,servicetype)
client = ros2svcclient(___,Name=Value)
[client,reqmsg] = ros2svcclient(___)

Description

example

client = ros2svcclient(node,servicename,servicetype) creates a service client of the specified servicetype regardless of whether a service server offering servicename is available. It attaches the client to the ROS 2 node specified by the ros2node object, node.

example

client = ros2svcclient(___,Name=Value) sets the rest of the properties based on the additional options specified by one or more Name=Value pair arguments, using the arguments from the previous syntax.

[client,reqmsg] = ros2svcclient(___) returns a new service request message in reqmsg, using any of the arguments from previous syntaxes. The message type of reqmsg is determined by the input service type. The message is initialized with default values. You can also create the request message using ros2message.

Properties

expand all

This property is read-only.

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

Example: "/gazebo/get_model_state"

This property is read-only.

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

Example: "gazebo_msgs/GetModelState"

This property is read-only.

Mode of storing requests in the queue, specified as a string or character vector. If the queue fills with requests waiting to be processed, then old requests will be dropped to make room for new. When set to "keeplast", the queue stores the number of requests set by the Depth property. Otherwise, when set to "keepall", the queue stores all requests up to the MATLAB® resource limits.

Example: "keeplast"

Data Types: char | string

This property is read-only.

Size of the request queue in number of requests stored in the queue, specified as a non-negative scalar integer. This only applies when History is set to "keeplast" or Durability is set to "transientlocal".

Example: 42

Data Types: double

This property is read-only.

Requirement on delivery guarantee of request, specified as a string or character vector. If "reliable", then delivery is guaranteed, but may retry calling multiple times. If "besteffort", then attempt delivery and do not retry. "reliable" setting is recommended for services.

Note

The quality of service settings must be compatible between service servers and clients for a connection to be made.

Example: "reliable"

Data Types: char | string

This property is read-only.

Requirement on persistence of the requests, specified as a string or character vector. If "volatile", then requests do not persist. If "transientlocal", then all recently sent requests persist, up to the number specified by Depth. "volatile" setting is recommended for services.

Note

The quality of service settings must be compatible between service servers and clients for a connection to be made.

Example: "volatile"

Data Types: char | string

Maximum amount of time allowed between sending a service request and receiving a response, specified as a positive scalar. The Deadline QoS parameter of service servers receiving request from the client must be less than or equal to the value of this parameter.

The default value is Inf which implies that after the service client sends a request, it can wait for an infinite period of time before receiving response to that request.

Length of time a service request is considered valid, specified as a positive scalar.

The default value is Inf which implies that a service request sent by service client is considered valid for infinite period of time.

Liveliness check of service server by service client, specified as automatic. This parameter is a measure of whether the service server is still alive.

Liveliness set to automatic implies that after the action client receives a response from the action server, the client counts the server as active for an additional Lease Duration.

Maximum amount of time before the service server connected to the client has to assert liveliness, specified as a positive scalar.

The default value is Inf which implies that the service server connected to the client can assert liveliness for infinite period of time.

Object Functions

ros2messageCreate ROS 2 message structures
callCall ROS or ROS 2 service server and receive a response
isServerAvailableDetermine if ROS or ROS 2 service server is available
waitForServerWait for ROS or ROS 2 service server to start

Examples

collapse all

Open Live Script

Create a sample ROS 2 network with two nodes.

node_1 = ros2node('node_1_service_client');
node_2 = ros2node('node_2_service_client');

Set up a service server and attach it to a ROS 2 node. Specify the callback function flipstring, which flips the input string. The callback function is defined at the end of this example.

server = ros2svcserver(node_1,'/test','test_msgs/BasicTypes',@flipString);

Set up a service client of the same service type and attach it to a different node.

client = ros2svcclient(node_2,'/test','test_msgs/BasicTypes');

Wait for the service client to connect to the server.

[connectionStatus,connectionStatustext] = waitForServer(client)
connectionStatus = logical
   1


connectionStatustext = 
'success'

Create a request message based on the client. Assign the string to the corresponding field in the message, string_value. 

request = ros2message(client);
request.string_value = 'hello world';

Check whether the service server is available. If it is, send a service request and wait for a response. Specify that the service waits 3 seconds for a response.

if(isServerAvailable(client))
    response = call(client,request,'Timeout',3);
end

The response is a flipped string from the request message which you see in the string_value field.

response.string_value
ans = 
'dlrow olleh'

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,request,"Timeout",3);
if ~status
    numCallFailures = numCallFailues + 1;
    fprintf("Call failure number %d. Error cause: %s\n",numCallFailures,statustext)
else
    disp(response.string_value)
end
dlrow olleh

The callback function used to flip the string is defined below. 

function resp = flipString(req,resp)
% FLIPSTRING Reverses the order of a string in REQ and returns it in RESP.
resp.string_value = fliplr(req.string_value);
end

Tips

  • ROS 2 service servers cannot communicate errors in callback execution directly to clients. In such situations, the servers only return the default response without any indication of failure. Hence, it is recommended to use try-catch blocks within the callback function, and set specific fields in the response message to communicate the success/failure of the callback execution on the server side.

Extended Capabilities

Version History

Introduced in R2021b

See Also

|

Topics