rossubscriber

Subscribe to messages on a topic

expand all in page

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.

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 = 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)

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

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

Object Functions

receiveWait for new ROS message
rosmessageCreate ROS messages

Examples

collapse all

Open Live Script

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 1.1402 seconds.
Initializing ROS master on http://192.168.0.10:58531.
Initializing global node /matlab_global_node_91925 with NodeURI http://bat6315glnxa64:43597/

exampleHelperROSCreateSampleNetwork

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

sub = rossubscriber('/scan');
pause(1);

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

msg2 = receive(sub,10)
msg2 = 
  ROS LaserScan message with properties:

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

  Use showdetails to show the contents of the message

Shutdown the timers used by sample network.

exampleHelperROSShutDownSampleNetwork

Shut down ROS network. 

rosshutdown
Shutting down global node /matlab_global_node_91925 with NodeURI http://bat6315glnxa64:43597/
Shutting down ROS master on http://192.168.0.10:58531.
.....
Open Live Script

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.1031 seconds.
Initializing ROS master on http://192.168.0.10:58348.
Initializing global node /matlab_global_node_31322 with NodeURI http://bat6315glnxa64:42563/

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');
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);
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_31322 with NodeURI http://bat6315glnxa64:42563/
Shutting down ROS master on http://192.168.0.10:58348.
.....
Open Live Script

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

Start the ROS master and node.

master = ros.Core;
Launching ROS Core...
.................Done in 1.0218 seconds.

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

Create a publisher and subscriber to send and receive a message over the ROS network.

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

Send a message over the network.

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

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

pause(1)
sub.LatestMessage
ans = 
  ROS String message with properties:

    MessageType: 'std_msgs/String'
           Data: 'hello world'

  Use showdetails to show the contents of the message

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

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

See Also

| |

Topics

Introduced in R2019b

ROS Toolbox Documentation

Support