Main Content

waitForServer

Wait for ROS or ROS 2 service server to start

Since R2021b

Description

waitForServer(client) waits until the service server is started up and available to receive requests. Press Ctrl+C to cancel the wait.

example

waitForServer(client,Timeout=timeoutperiod) specifies a timeout period in seconds using the name-value pair Timeout=timeoutperiod. If the service server does not start up 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 service client receives a service response.

[status,statustext] = waitForServer(___) returns a status indicating whether the service server is available, and a statustext that captures additional information about the status, using any of the arguments from the previous syntaxes. If the server is not available within the Timeout, status will be false, and this function will not display an error.

Examples

collapse all

Connect to a ROS network.

rosinit
Launching ROS Core...
Done in 0.45482 seconds.
Initializing ROS master on http://172.20.147.47:55175.
Initializing global node /matlab_global_node_34277 with NodeURI http://dcc300956glnxa64:41953/ and MasterURI http://localhost:55175.

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_34277 with NodeURI http://dcc300956glnxa64:41953/ and MasterURI http://localhost:55175.
Shutting down ROS master on http://172.20.147.47:55175.

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

Input Arguments

collapse all

ROS or ROS 2 service client, specified as a ros.ServiceClient or ros2serviceclient object handle, respectively. This service client enables you to send requests to the service server.

Output Arguments

collapse all

Status of the service server start up, returned as a logical scalar. If the server is not available within the timeout period, status will be false.

Note

Use the status output argument when you use waitForServer for code generation. This will avoid runtime errors and outputs the status instead, which can be reacted to in the calling code.

Status text associated with the service call status, returned as one of the following:

  • 'success' — The server is available.

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

  • 'timeout' — The server did not become available before the timeout period expired.

Extended Capabilities

Version History

Introduced in R2021b