Main Content

ros2publisher

Publish messages on a topic

expand all in page

Description

Use the ros2publisher object to publish messages on a topic. When messages are published on that topic, ROS 2 nodes that subscribe to that topic receive those messages directly.

Creation

Syntax

pub = ros2publisher(node,topic)
pub = ros2publisher(node,topic,type)
pub = ros2publisher(___,Name,Value)
[pub,msg] = ros2publisher(___)

Description

pub = ros2publisher(node,topic) creates a publisher, pub, for a topic with name topic that already exists on the ROS 2 network. node is the ros2node object handle to which the publisher should attach. The publisher gets the topic message type from the network topic list.

Note

The topic must be on the network topic list.

pub = ros2publisher(node,topic,type) creates a publisher for a topic and adds that topic to the network topic list. If the topic list already contains a matching topic, pub will be added to the list of publishers for that topic.

example

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

[pub,msg] = ros2publisher(___) returns a message, msg, that you can send with the publisher, pub. The message is initialized with default values. You can also get the ROS message using the ros2message function.

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 using its associated message type.

This property is set at creating by the TopicName argument. The value cannot be changed after creation.

Example: "/chatter"

Data Types: char

Message type of published messages, specified as a string scalar or character vector. This message type remains associated with the topic and must be used for new messages published.

This property is set at creation by the MessageType argument. The value cannot be changed after creation.

Example: "std_msgs/String"

Data Types: char

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. The queued messages will be sent to late-joining subscribers. 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 resource limits of MATLAB®.

Data Types: double

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

Example: 42

Data Types: double

Affects the guarantee of message delivery. If "reliable", then delivery is guaranteed, but may retry multiple times. If "besteffort", then delivery is attempt, but retried.

Example: "reliable"

Data Types: char | string

Affects persistence of messages in publishers, which allows late-joining subscribers to receive the number of old messages specified by Depth. If "volatile", then messages do not persist. If "transientlocal", then publisher will persist most recent messages.

Example: "volatile"

Data Types: char | string

Defines the expected interval for publishing consecutive messages to a topic, specified as a positive scalar. It sets the duration permitted between messages.

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

Example: 3

Data Types: double

Defines the maximum duration between publishing and message reception without considering the message as stale or expired, specified as a positive scalar. Messages that have expired are silently discarded.

The default value is Inf which implies the message can be published and received without being considered as expired, for an infinite duration of time.

Example: 5

Data Types: double

Defines the reporting level that the publishers will offer to notify the subscribers that they are alive, specified as a string.

Liveliness QoS policy set to "automatic" implies that a publisher is active for an additional Lease Duration when it publishes a message within that time frame.

Example: "automatic"

Data Types: char | string

Defines the maximum duration allowed to 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 publisher can assert its liveliness for infinite duration of time.

Example: 5

Data Types: double

Callback function to handle incompatible QoS settings in publisher, 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 publisher fails to publish 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 publisher is unable to publish within the specified 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

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 using its associated message type.

This property is set at creating by the TopicName argument. The value cannot be changed after creation.

Example: "/chatter"

Data Types: char

Message type of published messages, specified as a string scalar or character vector. This message type remains associated with the topic and must be used for new messages published.

This property is set at creation by the MessageType argument. The value cannot be changed after creation.

Example: "std_msgs/String"

Data Types: char

This property is read-only.

Determines the mode of storing messages in the queue. The queued messages will be sent to late-joining subscribers. 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 resource limits of MATLAB.

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.

Affects the guarantee of message delivery. If "reliable", then delivery is guaranteed, but may retry multiple times. If "besteffort", then delivery is attempt, but retried.

Example: "reliable"

Data Types: char | string

This property is read-only.

Affects persistence of messages in publishers, which allows late-joining subscribers to receive the number of old messages specified by Depth. If "volatile", then messages do not persist. If "transientlocal", then publisher will persist most recent messages.

Example: "volatile"

Data Types: char | string

Defines the expected interval for publishing consecutive messages to a topic, specified as a positive scalar. It sets the duration permitted between messages.

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

Example: 3

Data Types: double

Defines the maximum duration between publishing and message reception without considering the message as stale or expired, specified as a positive scalar. Messages that have expired are silently discarded.

The default value is Inf which implies the message can be published and received without being considered as expired, for an infinite duration of time. 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

Defines the reporting level that the publishers will offer to notify the subscribers that they are alive, specified as a string.

Liveliness QoS policy set to "automatic" implies that a publisher is active for an additional Lease Duration when it publishes a message within that time frame.

Example: "automatic"

Data Types: char | string

Defines the maximum duration allowed to 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 publisher can assert its liveliness for infinite duration of time. If the Lease Duration is set to 5, it implies that the publisher has a maximum duration of 5 seconds to demonstrate its liveliness. 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

ros2messageCreate ROS 2 message structures
sendPublish ROS 2 message to topic

Examples

collapse all

Open Live Script

Create a ROS 2 node.

node = ros2node('node1_empty_ros2_msg');

Create publisher and message.

chatPub = ros2publisher(node,"/chatter","std_msgs/String")
chatPub = 
  ros2publisher with properties:

        TopicName: '/chatter'
      MessageType: 'std_msgs/String'
         NodeName: '/node1_empty_ros2_msg'
          History: 'keeplast'
            Depth: 10
      Reliability: 'reliable'
       Durability: 'volatile'
         Deadline: Inf
         Lifespan: Inf
       Liveliness: 'automatic'
    LeaseDuration: Inf


msg = ros2message(chatPub)
msg = struct with fields:
    MessageType: 'std_msgs/String'
           data: ''

Extended Capabilities

Version History

Introduced in R2019b

See Also

| |

Topics