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...
Status before launching ros core :0
result before launching ros core: Microsoft.Management.Serv     2068 Services                   0    109,360 K
Microsoft.SharePoint.exe      9248 Console                    1    376,460 K

......Done in 7.1031 seconds.
* Inside getProcessPID function *
Process Name: rosmaster  - rosmaster  --core -p 54700 -w 3
Status before getting PID :0
Result before getting PID :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,460 K
WindowsTerminal.exe          10860 Console                    1     70,124 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,016 K

Result: 
WindowsTerminal.exe          10860 Console                    1     70,128 K

Status: 0
PID obtained: 10860
Status after getting PID :0
Result after getting PID :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,460 K
WindowsTerminal.exe          10860 Console                    1     70,128 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,016 K

* Exiting getProcessPID function *
Status after launching ros core :0
result after launching ros core: Microsoft.Management.Serv     2068 Services                   0    109,356 K
Microsoft.SharePoint.exe      9248 Console                    1    376,460 K
WindowsTerminal.exe          10860 Console                    1     70,128 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,016 K

Status before deleting node :0
Result before deleting node :Microsoft.Management.Serv     2068 Services                   0    109,360 K
Microsoft.SharePoint.exe      9248 Console                    1    376,460 K
WindowsTerminal.exe          10860 Console                    1     70,128 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,124 K
libmwros1server.exe          21352 Console                    1     29,488 K

Status after deleting node :0
Result after deleting node :Microsoft.Management.Serv     2068 Services                   0    109,356 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,128 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,084 K

Initializing ROS master on http://172.31.78.36:54700.
Initializing global node /matlab_global_node_41904 with NodeURI http://vdi-ah2wsp-001:64594/ and MasterURI http://localhost:54700.

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.5467
          AngleMax: 0.5467
    AngleIncrement: 0.0017
     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

Status before deleting node :0
Result before deleting node :Microsoft.Management.Serv     2068 Services                   0    109,360 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,316 K
libmwros1server.exe          12768 Console                    1     32,476 K
libmwros1server.exe          16724 Console                    1     33,272 K
libmwros1server.exe           8552 Console                    1     33,128 K
libmwros1server.exe          10272 Console                    1     32,844 K

Status after deleting node :0
Result after deleting node :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,276 K
libmwros1server.exe          12768 Console                    1     32,480 K
libmwros1server.exe           8552 Console                    1     33,128 K
libmwros1server.exe          10272 Console                    1     32,844 K

Status before deleting node :0
Result before deleting node :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,276 K
libmwros1server.exe          12768 Console                    1     32,500 K
libmwros1server.exe           8552 Console                    1     33,128 K
libmwros1server.exe          10272 Console                    1     32,844 K

Status after deleting node :0
Result after deleting node :Microsoft.Management.Serv     2068 Services                   0    109,356 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,236 K
libmwros1server.exe          12768 Console                    1     32,500 K
libmwros1server.exe          10272 Console                    1     32,844 K

Status before deleting node :0
Result before deleting node :Microsoft.Management.Serv     2068 Services                   0    109,356 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     30,236 K
libmwros1server.exe          12768 Console                    1     32,500 K
libmwros1server.exe          10272 Console                    1     32,844 K

Status after deleting node :0
Result after deleting node :Microsoft.Management.Serv     2068 Services                   0    109,356 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     31,448 K
libmwros1server.exe          12768 Console                    1     32,552 K

Shut down ROS network.

rosshutdown

Shutting down global node /matlab_global_node_41904 with NodeURI http://vdi-ah2wsp-001:64594/ and MasterURI http://localhost:54700.
Status before deleting node :0
Result before deleting node :Microsoft.Management.Serv     2068 Services                   0    109,356 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     31,448 K
libmwros1server.exe          12768 Console                    1     32,576 K

Status after deleting node :0
Result after deleting node :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     31,408 K

Shutting down ROS master on http://172.31.78.36:54700.
Status before deleting core :0
Result before deleting core :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K
WindowsTerminal.exe          10860 Console                    1     70,132 K
rosmaster.exe                21056 Console                    1      4,968 K
python.exe                   19980 Console                    1      4,736 K
python.exe                   13016 Console                    1     31,420 K

* Inside killROSProcess function *
Status after Process Killed: 0
Result after Process Killed: SUCCESS: Sent termination signal to the process with PID 10860.

Status after deleting core :0
Result after deleting core :Microsoft.Management.Serv     2068 Services                   0    109,328 K
Microsoft.SharePoint.exe      9248 Console                    1    376,580 K

* Exiting killROSProcess function *

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.