Main Content

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. 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

Description

example

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.

example

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.

example

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

expand all

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

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

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.

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.

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};

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

receiveWait for new ROS message
rosmessageCreate ROS messages

Examples

collapse all

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.3104 seconds.
Initializing ROS master on http://192.168.0.10:53277.
Initializing global node /matlab_global_node_20625 with NodeURI http://dcc282524glnxa64:46327/
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_20625 with NodeURI http://dcc282524glnxa64:46327/
Shutting down ROS master on http://192.168.0.10:53277.

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 0.90795 seconds.
Initializing ROS master on http://192.168.0.10:57038.
Initializing global node /matlab_global_node_78798 with NodeURI http://dcc282524glnxa64:45071/

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_78798 with NodeURI http://dcc282524glnxa64:45071/
Shutting down ROS master on http://192.168.0.10:57038.

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.065 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')

Compatibility Considerations

expand all

Behavior change in future release

Extended Capabilities

Introduced in R2019b