rossubscriber

Subscribe to messages on a topic

Description

Use rossubscriber to create a ROS subscriber for receiving messages on the ROS network. To send messages, use rospublisher. The most reliable method to receive messages continuously as they are published on the ROS network is to create a callback for the rossubscriber object. For more information, see Create A Subscriber That Uses A Callback Function. Alternatively, to wait for a new ROS message, use the receive function with your created subscriber.

The Subscriber object created by the rossubscriber function represents a subscriber on the ROS network. The Subscriber object subscribes to an available topic or to a topic that it creates. This topic has an associated message type. Publishers can send messages over the network that the Subscriber object receives.

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.

You can create a Subscriber object by using the rossubscriber function, or by calling ros.Subscriber:

• rossubscriber works only with the global node using rosinit. It does not require a node object handle as an argument.

• ros.Subscriber works with additional nodes that are created using ros.Node. It requires a node object handle as the first argument.

Creation

Syntax

sub = rossubscriber(topicname)

sub = rossubscriber(topicname,msgtype)

sub = rossubscriber(topicname,callback)

sub = rossubscriber(topicname, msgtype,callback)

sub = rossubscriber(___,Name,Value)

sub = rossubscriber(___,"DataFormat","struct")

sub = ros.Subscriber(node,topicname)

sub = ros.Subscriber(node,topicname,msgtype)

sub = ros.Subscriber(node,topicname,callback)

sub = ros.Subscriber(node,topicname,type,callback)

sub = ros.Subscriber(___,"BufferSize",value)

sub = ros.Subscriber(___,"DataFormat","struct")

Description

sub = rossubscriber(topicname) subscribes to a topic with the given TopicName.The topic must already exist on the ROS master topic list with an established message type. When ROS nodes publish messages on that topic, MATLAB^® receives those messages through this subscriber.

sub = rossubscriber(topicname,msgtype) subscribes to a topic that has the specified name, TopicName, and type, MessageType. If the topic list on the ROS master does not include a topic with that specified name and type, it is added to the topic list. Use this syntax to avoid errors when subscribing to a topic before a publisher has added the topic to the topic list on the ROS master.

sub = rossubscriber(topicname,callback) specifies a callback function, callback, that runs when the subscriber object handle receives a topic message. Use this syntax to avoid the blocking receive function. The callback function can be a single function handle or a cell array. The first element of the cell array must be a function handle or a string containing the name of a function. The remaining elements of the cell array can be arbitrary user data that is passed to the callback function.

sub = rossubscriber(topicname, msgtype,callback) specifies a callback function and subscribes to a topic that has the specified name, TopicName, and type, MessageType.

sub = rossubscriber(___,Name,Value) provides additional options specified by one or more Name,Value pair arguments using any of the arguments from previous syntaxes. Name is the property name and Value is the corresponding value.

sub = rossubscriber(___,"DataFormat","struct") uses message structures instead of objects. For more information, see ROS Message Structures

sub = ros.Subscriber(node,topicname) subscribes to a topic with name, TopicName. The node is the ros.Node object handle that this publisher attaches to.

sub = ros.Subscriber(node,topicname,msgtype) specifies the message type, MessageType, of the topic. If a topic with the same name exists with a different message type, MATLAB creates a new topic with the given message type.

sub = ros.Subscriber(node,topicname,callback) specifies a callback function, and optional data, to run when the subscriber object receives a topic message. See NewMessageFcn for more information about the callback function.

sub = ros.Subscriber(node,topicname,type,callback) specifies the topic name, message type, and callback function for the subscriber.

sub = ros.Subscriber(___,"BufferSize",value) specifies the queue size in BufferSize for incoming messages. You can use any combination of previous inputs with this syntax.

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

Properties

TopicName — Name of the subscribed topic

string scalar | character vector

This property is read-only.

Name of the subscribed topic, specified as a string scalar or character vector. If the topic does not exist, the object creates the topic using its associated message type.

Example: "/chatter"

Data Types: char | string

MessageType — Message type of subscribed messages

string scalar | character vector

This property is read-only.

Message type of subscribed messages, specified as a string scalar or character vector. This message type remains associated with the topic.

Example: "std_msgs/String"

Data Types: char | string

LatestMessage — Latest message sent to the topic

Message object

Latest message sent to the topic, specified as a Message object. The Message object is specific to the given MessageType. If the subscriber has not received a message, then the Message object is empty.

BufferSize — Buffer size

1 (default) | scalar

Buffer size of the incoming message queue, specified as the comma-separated pair consisting of "BufferSize" and a scalar. If messages arrive faster than your callback can process them, they are deleted once the incoming queue is full.

MATLAB has a default recursion limit of 500. Hence, if you are specifying a buffer size value N greater than 500, you must change the MATLAB recursion limit to N using this code:

set(0,'RecursionLimit',N)

Ensure that you do not specify excessively high recursion limit which results in exceeding your available stack space.

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 or a string representing a function name. In subsequent elements, specify user data.

The subscriber callback function requires at least two input arguments. The first argument, src, is the associated subscriber object. The second argument, msg, is the received message object. The function header for the callback is:

function subCallback(src,msg)

Specify the NewMessageFcn property as:

sub.NewMessageFcn = @subCallback;

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 subCallback(src,msg,userData)

Specify the NewMessageFcn property as:

sub.NewMessageFcn = {@subCallback,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

receive	Wait for new ROS message
rosmessage	Create ROS messages

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 0.82586 seconds.
Initializing ROS master on http://172.20.148.53:52908.
Initializing global node /matlab_global_node_48948 with NodeURI http://dcc867993glnxa64:33959/ and MasterURI http://localhost:52908.

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: [1x1 struct]
          AngleMin: -0.5467
          AngleMax: 0.5467
    AngleIncrement: 0.0017
     TimeIncrement: 0
          ScanTime: 0.0330
          RangeMin: 0.4500
          RangeMax: 10
            Ranges: [640x1 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_48948 with NodeURI http://dcc867993glnxa64:33959/ and MasterURI http://localhost:52908.
Shutting down ROS master on http://172.20.148.53:52908.

Create A Subscriber That Uses A Callback Function

You can trigger callback functions when subscribers receive messages. Specify the callback when you create it or use the NewMessageFcn property.

Connect to a ROS network.

rosinit

Launching ROS Core...
.Done in 1.1466 seconds.
Initializing ROS master on http://172.20.148.53:60884.
Initializing global node /matlab_global_node_32814 with NodeURI http://dcc867993glnxa64:43731/ and MasterURI http://localhost:60884.

Setup a publisher to publish a message to the '/chatter' topic. This topic is used to trigger the subscriber callback. Specify the Data property of the message. Wait 1 second to allow the publisher to register with the network.

pub = rospublisher('/chatter','std_msgs/String','DataFormat','struct');
msg = rosmessage(pub);
msg.Data = 'hello world';
pause(1)

Set up a subscriber with a specified callback function. The exampleHelperROSChatterCallback function displays the Data inside the received message.

sub = rossubscriber('/chatter',@exampleHelperROSChatterCallback,'DataFormat','struct');
pause(1)

Send the message via the publisher. The subscriber should execute the callback to display the new message. Wait for the message to be received.

send(pub,msg);
pause(1)

ans = 
'hello world'

Shut down ROS network.

rosshutdown

Shutting down global node /matlab_global_node_32814 with NodeURI http://dcc867993glnxa64:43731/ and MasterURI http://localhost:60884.
Shutting down ROS master on http://172.20.148.53:60884.

Use ROS Subscriber Object

Use a ROS Subscriber object to receive messages over the ROS network.

Start the ROS core and node.

master = ros.Core;

Launching ROS Core...
.Done in 1.0961 seconds.

node = ros.Node('/test');

Create a publisher and subscriber to send and receive a message over the ROS network. Use ROS messages as structures.

pub = ros.Publisher(node,'/chatter','std_msgs/String','DataFormat','struct');
sub = ros.Subscriber(node,'/chatter','std_msgs/String','DataFormat','struct');

Send a message over the network.

msg = rosmessage(pub);
msg.Data = 'hello world';
send(pub,msg)

View the message data using the LatestMessage property of the Subscriber object.

pause(1)
sub.LatestMessage

ans = struct with fields:
    MessageType: 'std_msgs/String'
           Data: 'hello world'

Clear the publisher, subscriber, and ROS node. Shut down the ROS master.

clear('pub','sub','node')
clear('master')

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Supported only for struct messages.

• MessageType argument must be specified.

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

• When no message is received, the LatestMessage property returns a message with default values based on the message type.

• MEX code generation not supported.

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.