Main Content

ros2subscriber

Subscribe to messages on a topic

expand all in page

Description

Use the ros2subscriber to receive messages on a topic. When ROS 2 nodes publish messages on that topic, MATLAB® will receive those message through this subscriber.

Creation

Syntax

sub = ros2subscriber(node,topic)
sub = ros2subscriber(node,topic,type)
sub = ros2subscriber(node,topic,callback)
sub = ros2subscriber(node,topic,type,callback)
sub = ros2subscriber(___,Name,Value)

Description

sub = ros2subscriber(node,topic) creates a subscriber, sub, for a topic with name topic that already exists on the ROS 2 network. node is the ros2node object to which this subscriber attaches. The subscriber gets the topic message type from the network topic list.

Note

The topic must be on the network topic list.

example

sub = ros2subscriber(node,topic,type) creates a subscriber for a topic and adds that topic to the network topic list. If the topic list already contains a matching topic, sub will be added to the list of subscribers for that topic. The type must be the same as the topic. Use this syntax to avoid errors when it is possible for the subscriber to subscribe to a topic before a topic has been added to the network.

example

sub = ros2subscriber(node,topic,callback) specifies a callback function, callback, and optional data, to run when the subscriber object handle receives a topic message. Use this syntax if action needs to be taken on every message, while not blocking code execution. callback can be a single function handle or a cell array. The first element of the cell array needs to 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 will be passed to the callback function.

Note

The subscriber callback function uses a single input argument, the received message object, msg. The function header for the callback is as follows:

function subCallback(msg)
You pass additional parameters to the callback function by including both the callback function and the parameters as elements of a cell array when setting the callback.

example

sub = ros2subscriber(node,topic,type,callback) specifies a callback function callback, and subscribes to a topic that has the specified name topic and message type type.

example

sub = ros2subscriber(___,Name,Value) specifies additional options using one or more name-value pair arguments. Specify name-value pair arguments after all other input arguments.

Input Arguments

expand all

A ros2node object on the network.

Name of the published topic, specified as a string scalar or character vector. If the topic does not exist, the object creates the topic based on the associated message type.

Example: "/chatter"

This property is read-only.

The message type of subscribed messages.

Example: "std_msgs/String"

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Determines the mode of storing messages in the queue. If the queue fills with messages waiting to be processed, then old messages will be dropped to make room for new. If set to "keeplast", the queue stores the number of messages set by the Depth property. If set to "keepall", the queue stores all messages up to the MATLAB resource limits.

Number of messages stored in the message queue when History is set to "keeplast".

Example: 42

Data Types: double

Requirement on the guarantee of message delivery. If "reliable", then delivery is guaranteed, but may retry multiple times. If "besteffort", then attempt delivery and do not retry.

Example: "reliable"

Data Types: char | string

Requirement on the persistence of messages in connected publishers, which allows late-joining subscribers to receive the number of old messages specified by Depth. If "volatile", then message persistence is not required and no messages are requested when the subscriber joins the network. If "transientlocal", then the subscriber will require publishers to persist messages, and will request the number of messages specified by Depth.

Example: "volatile"

Data Types: char | string

Outlines the permissible duration between message receptions by subscriber, specified as a positive scalar. In case the messages are not received within the deadline, the client application receives a notification.

The default value is Inf which implies that expected interval between subsequent message receptions is infinite.

Example: 3

Data Types: double

Defines the duration a message is deemed valid, beyond which it will not be received by subscriber, specified as a positive scalar. Messages that have expired are silently discarded.

The default value is Inf which implies that a message is deemed valid and received by subscriber for infinite duration.

Example: 5

Data Types: double

Determines the reporting standard expected from the publishers to which they are subscribed, specified as a string.

Liveliness set to "automatic" implies that when any of the publishers has published a message, the system will consider all publishers of the node to be alive for an additional Lease Duration.

Example: "automatic"

Data Types: char | string

Defines the maximum duration for which a subscriber expects a publisher to demonstrate its liveliness before the system considers it to have lost liveliness, specified as a positive scalar. Losing liveliness could serve as an indication of failure.

Example: 5

Data Types: double

Callback function to handle incompatible QoS settings in subscriber, specified as a function handle with the following input arguments:

  • total_count

  • total_count_change

  • last_policy_kind

This is an example of the function signature header:

pub = ros2publisher(myNode, "/my_topic", "sensor_msgs/Image", "IncompatibleQoSCallback", @incompatibleQoS_callback);
function incompatibleQoS_callback(total_count, total_count_change, last_policy_kind)

Data Types: function_handle

Callback function to handle deadline missed event when the subscriber does not receive any messages within the specified deadline, specified as a function handle with the following input arguments:

  • total_count

  • total_count_change

This is an example of the function signature header:

pub = ros2publisher(myNode, "/my_topic", "sensor_msgs/Image", "DeadlineMissedCallback", @deadlineMissed_callback);
function deadlineMissed_callback(total_count, total_count_change)

Data Types: function_handle

Callback function to handle liveliness lost event when the subscriber has noticed that one or more publishers on the topic did not assert their liveliness within the lease duration, specified as a function handle with the following input arguments:

  • alive_count

  • not_alive_count

  • alive_count_change

  • not_alive_count_change

This is an example of the function signature header:

pub = ros2publisher(myNode, "/my_topic", "sensor_msgs/Image", "LivelinessLostCallback", @livelinessLost_callback);
function livelinessLost_callback(alive_count, not_alive_count, alive_count_change, not_alive_count_change)

Data Types: function_handle

Callback function to handle message lost event when he subscriber missed receiving messages because of network issues, buffer overflows, or other communication problems, causing message loss; specified as a function handle with the following input arguments:

  • total_count –– Total number of messages lost.

  • total_count_change –– Number of messages lost since last callback.

This is an example of the function signature header:

sub = ros2subscriber(myNode, "/my_topic", "sensor_msgs/Image", "MessageLostCallback", @messageLost_callback);
function messageLost_callback(total_count, total_count_change)

Data Types: function_handle

Properties

expand all

Name of the published topic, specified as a string scalar or character vector. If the topic does not exist, the object creates the topic based on the associated message type.

Example: "/chatter"

Data Types: char

This property is read-only.

The message type of subscribed messages.

Example: "std_msgs/String"

Data Types: char | string

This property is read-only.

The most recently received ROS 2 message, specified as a Message object handle, received.

This property is read-only.

Callback function for subscriber callbacks.

Note

The subscriber callback function uses a single input argument, the received message object, msg. The function header for the callback is as follows:

function subCallback(msg)
You pass additional parameters to the callback function by including both the callback function and the parameters as elements of a cell array when setting the callback.

This property is read-only.

Determines the mode of storing messages in the queue. If the queue fills with messages waiting to be processed, then old messages will be dropped to make room for new. When set to "keeplast", the queue stores the number of messages set by the Depth property. Otherwise, when set to "keepall", the queue stores all messages up to the MATLAB resource limits.

Example: "keeplast"

Data Types: char | string

This property is read-only.

Number of messages stored in the message queue when History is set to "keeplast".

Example: 42

Data Types: double

This property is read-only.

Requirement on the guarantee of message delivery. If "reliable", then delivery is guaranteed, but may retry multiple times. If "besteffort", then attempt delivery and do not retry.

Example: "reliable"

Data Types: char | string

This property is read-only.

Requirement on the persistence of messages in connected publishers, which allows late-joining subscribers to receive the number of old messages specified by Depth. If "volatile", then message persistence is not required and no messages are requested when the subscriber joins the network. If "transientlocal", then the subscriber will require publishers to persist messages, and will request the number of messages specified by Depth.

Example: "volatile"

Data Types: char | string

Outlines the permissible duration between message receptions by subscriber, specified as a positive scalar. In case the messages are not received within the deadline, the client application receives a notification.

The default value is Inf which implies that expected interval between subsequent message receptions is infinite. If Deadline is set to 3, it ensures that the subscriber subscribes to every succeeding message is published to the topic after 3 seconds of subscribing to the preceding message.

Example: 3

Data Types: double

Defines the duration a message is deemed valid, beyond which it will not be received by subscriber, specified as a positive scalar. Messages that have expired are silently discarded.

The default value is Inf which implies that a message is deemed valid and received by subscriber for infinite duration. If Lifespan is set to 5, it means that a message is considered valid for 5 seconds after being published. If subscriber has not received the message within that time frame, the message is considered expired.

Example: 5

Data Types: double

Determines the reporting standard expected from the publishers to which they are subscribed, specified as a string.

Liveliness set to "automatic" implies that when any of the publishers has published a message, the system will consider all publishers of the node to be alive for an additional Lease Duration.

Example: "automatic"

Data Types: char | string

Defines the maximum duration for which a subscriber expects a publisher to demonstrate its liveliness before the system considers it to have lost liveliness, specified as a positive scalar. Losing liveliness could serve as an indication of failure.

The default value is Inf which implies that a publisher can assert its liveliness for infinite period of time. If the Lease Duration is set to 5, it implies that the subscriber can expect the publisher to demonstrate its liveliness within a maximum of 5 seconds. If the publisher does not send any messages or explicitly assert its liveliness within that time frame, it is considered to have lost liveliness.

Example: 5

Data Types: double

Object Functions

receiveWait for new message
ros2messageCreate ROS 2 message structures

Examples

collapse all

Open Live Script

This example shows how to publish and subscribe to topics in a ROS 2 network.

The primary mechanism for ROS 2 nodes to exchange data is to send and receive messages. Messages are transmitted on a topic and each topic has a unique name in the ROS 2 network. If a node wants to share information, it must use a publisher to send data to a topic. A node that wants to receive that information must use a subscriber for that same topic. Besides its unique name, each topic also has a message type, which determines the type of messages that are allowed to be transmitted in the specific topic.

This publisher-subscriber communication has these characteristics:

  • Topics are used for many-to-many communication. Multiple publishers can send messages to the same topic and multiple subscribers can receive them.

  • Publisher and subscribers are decoupled through topics and can be created and destroyed in any order. A message can be published to a topic even if there are no active subscribers.

Besides how to publish and subscribe to topics in a ROS 2 network, this example also shows how to:

  • Wait until a new message is received, or

  • Use callbacks to process new messages in the background

Prerequisites: Get Started with ROS 2, Connect to a ROS 2 Network

Subscribe and Wait for Messages

Create a sample ROS 2 network with several publishers and subscribers.

exampleHelperROS2CreateSampleNetwork

Use ros2 topic list to see which topics are available.

ros2 topic list
/parameter_events
/pose
/rosout
/scan

Assume you want to subscribe to the /scan topic. Use ros2subscriber to subscribe to the /scan topic. Specify the name of the node with the subscriber. If the topic already exists in the ROS 2 network, ros2subscriber detects its message type automatically, so you do not need to specify it.

detectNode = ros2node("/detection");
pause(5)
laserSub = ros2subscriber(detectNode,"/scan");
pause(5)

Use receive to wait for a new message. Specify a timeout of 10 seconds. The output scanData contains the received message data. status indicates whether a message was received successfully and statustext provides additional information about the status.

[scanData,status,statustext] = receive(laserSub,10);

You can now remove the subscriber laserSub and the node associated to it.

clear laserSub
clear detectNode

Subscribe Using Callback Functions

Instead of using receive to get data, you can specify a function to be called when a new message is received. This allows other MATLAB code to execute while the subscriber is waiting for new messages. Callbacks are essential if you want to use multiple subscribers.

Subscribe to the /pose topic, using the callback function exampleHelperROS2PoseCallback, which takes a received message as the input. One way of sharing data between your main workspace and the callback function is to use global variables. Define two global variables pos and orient.

controlNode = ros2node("/base_station");
pause(5)
poseSub = ros2subscriber(controlNode,"/pose",@exampleHelperROS2PoseCallback);
global pos
global orient

The global variables pos and orient are assigned in the exampleHelperROS2PoseCallback function when new message data is received on the /pose topic.

function exampleHelperROS2PoseCallback(message)    
    % Declare global variables to store position and orientation
    global pos
    global orient
    
    % Extract position and orientation from the ROS message and assign the
    % data to the global variables.
    pos = [message.linear.x message.linear.y message.linear.z];
    orient = [message.angular.x message.angular.y message.angular.z];
end

Wait a moment for the network to publish another /pose message. Display the updated values.

pause(3)
disp(pos)
       0.00235920447111606       -0.0201184589892978        0.0203969078651195

disp(orient)
       -0.0118389124011118       0.00676849978014866        0.0387860955311228

If you type in pos and orient a few times in the command line you can see that the values are continuously updated.

Stop the pose subscriber by clearing the subscriber variable

clear poseSub
clear controlNode

Note: There are other ways to extract information from callback functions besides using globals. For example, you can pass a handle object as additional argument to the callback function. See the Create Callbacks for Graphics Objects documentation for more information about defining callback functions.

Publish Messages

Create a publisher that sends ROS 2 string messages to the /chatter topic.

chatterPub = ros2publisher(node_1,"/chatter","std_msgs/String");

Create and populate a ROS 2 message to send to the /chatter topic.

chatterMsg = ros2message(chatterPub);
chatterMsg.data = 'hello world';

Use ros2 topic list to verify that the /chatter topic is available in the ROS 2 network.

ros2 topic list
/chatter
/parameter_events
/pose
/rosout
/scan

Define a subscriber for the /chatter topic. exampleHelperROS2ChatterCallback is called when a new message is received, and displays the string content in the message.

chatterSub = ros2subscriber(node_2,"/chatter",@exampleHelperROS2ChatterCallback)
chatterSub = 
  ros2subscriber with properties:

        TopicName: '/chatter'
    LatestMessage: []
      MessageType: 'std_msgs/String'
    NewMessageFcn: @exampleHelperROS2ChatterCallback
          History: 'keeplast'
            Depth: 10
      Reliability: 'reliable'
       Durability: 'volatile'

Publish a message to the /chatter topic. Observe that the string is displayed by the subscriber callback.

send(chatterPub,chatterMsg)
pause(3)
ans = 
'hello world'

The exampleHelperROS2ChatterCallback function was called when the subscriber received the string message.

Disconnect From ROS 2 Network

Remove the sample nodes, publishers and subscribers from the ROS 2 network. Also clear the global variables pos and orient

clear global pos orient
clear

Next Steps

Extended Capabilities

Version History

Introduced in R2019b

See Also

|

Topics