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.

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

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

  • robotics.ros.Subscriber works with additional nodes that are created using robotics.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 = robotics.ros.Subscriber(node,topicname)
sub = robotics.ros.Subscriber(node,topicname,msgtype)
sub = robotics.ros.Subscriber(node,topicname,callback)
sub = robotics.ros.Subscriber(node,topicname,type,callback)
sub = robotics.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. callback 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 = robotics.ros.Subscriber(node,topicname) subscribes to a topic with name, TopicName. node is the robotics.ros.Node object handle that this publisher attaches to.

example

sub = robotics.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 = robotics.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 = robotics.ros.Subscriber(node,topicname,type,callback) specifies the topic name, message type, and callback function for the subscriber.

sub = robotics.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 and 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

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

rosinit
Initializing ROS master on http://bat583203glnxa64:42677/.
Initializing global node /matlab_global_node_20085 with NodeURI http://bat583203glnxa64:37463/
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 ROS network.

rosshutdown
Shutting down global node /matlab_global_node_20085 with NodeURI http://bat583203glnxa64:37463/
Shutting down ROS master on http://bat583203glnxa64:42677/.

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
Initializing ROS master on http://bat4726glnxa64:43921/.
Initializing global node /matlab_global_node_69581 with NodeURI http://bat4726glnxa64:42935/

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)

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

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

Send 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'

Shutdown ROS network.

rosshutdown
Shutting down global node /matlab_global_node_69581 with NodeURI http://bat4726glnxa64:42935/
Shutting down ROS master on http://bat4726glnxa64:43921/.

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

Start the ROS master and node.

master = robotics.ros.Core;
node = robotics.ros.Node('/test');

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

pub = robotics.ros.Publisher(node,'/chatter','std_msgs/String');
pause(1)
sub = robotics.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')

Introduced in R2015a