receive

Wait for new ROS message

Syntax

msg = receive(sub)

msg = receive(sub,timeout)

[msg,status,statustext] = receive(___)

Description

msg = receive(sub) waits for MATLAB^® to receive a topic message from the specified subscriber, sub, and returns it as msg. Alternatively, for the most more reliable way to receive messages continuously as they are published on the ROS network, consider using a callback function with the rossubscriber object.

msg = receive(sub,timeout) specifies in timeout the number of seconds to wait for a message. If a message is not received within the timeout limit, this function will display an error.

[msg,status,statustext] = receive(___) returns a status indicating whether a message has been received successfully, and a statustext that captures additional information about the status, using any of the arguments from the previous syntaxes. If an error condition occurs, such as no message received within the specified timeout, the status will be false, and this function will not display an error.

Examples

Create A Subscriber and Get Data From ROS

Connect to a ROS network. Set up a sample ROS network. The '/scan' topic is being published on the network.

rosinit

Launching ROS Core...
..Done in 2.7558 seconds.
Initializing ROS master on http://192.168.88.1:54832.
Initializing global node /matlab_global_node_90972 with NodeURI http://ah-avijayar:56095/

exampleHelperROSCreateSampleNetwork

Create a subscriber for the '/scan' topic using message structures. Wait for the subscriber to register with the master.

sub = rossubscriber('/scan','DataFormat','struct');
pause(1);

Receive data from the subscriber as a ROS message structure. Specify a 10-second timeout.

[msg2,status,statustext] = receive(sub,10)

msg2 = struct with fields:
       MessageType: 'sensor_msgs/LaserScan'
            Header: [1×1 struct]
          AngleMin: -0.5216
          AngleMax: 0.5243
    AngleIncrement: 0.0016
     TimeIncrement: 0
          ScanTime: 0.0330
          RangeMin: 0.4500
          RangeMax: 10
            Ranges: [640×1 single]
       Intensities: []

status = logical
   1

statustext = 
'success'

Shutdown the timers used by sample network.

exampleHelperROSShutDownSampleNetwork

Shut down ROS network.

rosshutdown

Shutting down global node /matlab_global_node_90972 with NodeURI http://ah-avijayar:56095/
Shutting down ROS master on http://192.168.88.1:54832.

Input Arguments

sub — ROS subscriber

Subscriber object handle

ROS subscriber, specified as a Subscriber object handle. You can create the subscriber using rossubscriber.

timeout — Timeout for receiving a message

scalar in seconds

Timeout for receiving a message, specified as a scalar in seconds.

Output Arguments

msg — ROS message

Message object handle | structure

ROS message, returned as a Message object handle or structure.

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.

status — Status of the message reception

logical scalar

Status of the message reception, returned as a logical scalar. If no message is received, status will be false.

Note

Use the status output argument when you use receive 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 message reception status

character vector

Status text associated with the message reception, returned as one of the following:

• 'success' — The message was successfully received.

• 'timeout' — The message was not received within the specified timeout.

• 'unknown' — The message was not received due to unknown errors.

Tips

For code generation:

• Use the status output argument when you call receive in the entry-point function. This will avoid runtime errors and instead, outputs the status of message reception, which can be reacted to in the calling code.

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Supported only for struct messages.

• To monitor the message reception status and react in the calling code, use the status output argument. This will avoid runtime errors when no message is received.

Version History

Introduced in R2019b

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.