ros2publisher
Publish messages on a topic
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
Description
creates a publisher, pub
= ros2publisher(node
,topic
)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.
specifies additional options using one or more name-value pair arguments. Specify
name-value pair arguments after all other input arguments.pub
= ros2publisher(___,Name,Value
)
[
returns a message, pub
,msg
]
= ros2publisher(___)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
node
— ROS 2 node
node
structure
A ros2node
object on the network.
topic
— Name of the published topic
string scalar | character vector
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
type
— Message type of published messages
string scalar | character vector
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
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.
History
— Mode of storing messages in the queue
"keeplast"
(default) | "keepall"
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
Depth
— Size of the message queue
positive integer
Number of messages stored in the message queue when History
is set to "keeplast"
.
Example: 42
Data Types: double
Reliability
— Delivery guarantee of messages
"reliable"
(default) | "besteffort"
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
Durability
— Persistence of messages
"volatile"
(default) | "transientlocal"
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
Deadline
— Expected interval between publishing consecutive messages
Inf
(default) | positive scalar
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
Lifespan
— Message validity window between publishing and reception
Inf
(default) | positive scalar
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
Liveliness
— Publisher aliveness asserting protocol
"automatic"
(default)
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
Lease Duration
— Maximum time window between liveliness assertions
Inf
(default) | positive scalar
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
IncompatibleQoSCallback
— Callback function to handle incompatible QoS settings
function handle
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
DeadlineMissedCallback
— Callback function to handle deadline missed event
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
LivelinessLostCallback
— Callback function to handle liveliness lost event
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
TopicName
— Name of the published topic
string scalar | character vector
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
MessageType
— Message type of published messages
string scalar | character vector
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
History
— Message queue mode
"keeplast"
(default) | "keepall"
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
Depth
— Size of the message queue
positive integer
This property is read-only.
Number of messages stored in the message queue when History
is
set to "keeplast"
.
Example: 42
Data Types: double
Reliability
— Delivery guarantee of messages
"reliable"
(default) | "besteffort"
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
Durability
— Persistence of messages
"volatile"
(default) | "transientlocal"
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
Deadline
— Expected interval between publishing consecutive messages
Inf
(default) | positive scalar
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
Lifespan
— Message validity window between publishing and reception
Inf
(default) | positive scalar
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
Liveliness
— Publisher aliveness asserting protocol
"automatic"
(default)
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
Lease Duration
— Maximum time window between liveliness assertions
Inf
(default) | positive scalar
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
ros2message | Create ROS 2 message structures |
send | Publish ROS 2 message to topic |
Examples
Create an Empty ROS 2 Message
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
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
MessageType
argument must be specified.ros2publisher(___) does not return a message,
msg
, that you can send with the publisher,pub
. You can get the ROS message using theros2message
function.MEX code generation not supported.
Version History
Introduced in R2019b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)