Manage Quality of Service Policies in ROS 2
Quality of Service (QoS) policy options allow for changing the behavior of communication within a ROS 2 network. QoS policies are modified for specific communication objects, such as publishers and subscribers, and change the way that messages are handled in the object and transported between them. For any messages to pass between two communication objects, their QoS policies must be compatible.
The available Quality of Service policies in ROS 2 are:
History
- Message queue modeDepth
- Message queue sizeReliability
- Delivery guarantee of messagesDurability
- Persistence of messagesDeadline
- Expected interval between consecutive messagesLifespan
- Message validity window after receptionLiveliness
- Entity aliveness asserting protocolLeaseDuration
- Maximum time window between liveliness assertions
For more information, see About Quality of Service Settings.
History and Depth
The History
and Depth
QoS policies determine the behavior of communication objects when messages are being made available faster than they can be processed. This is primarily a concern for subscribers that are receiving messages while still processing the previous message. Messages are placed into a processing queue, which can affect publishers as well. History
has the options of:
"keeplast"
- The message processing queue has a maximum size equal to theDepth
value. If the queue is full, the oldest messages are dropped to make room for newer ones."keepall"
- The message processing queue attempts to keep all messages received in the queue until processed.
Under either History
setting, the queue size is subject to hardware resource limits. If the subscriber calls a callback when new messages are received, the queue size is also limited by the maximum recursion limit.
In situations where it is important to process all messages, increasing the Depth
value or using History,"keepall"
is recommended.
This example shows how to set up a publisher and subscriber for sending and receiving point cloud messages. The publisher Depth
is 20 and the subscriber History
is set to "keepall"
. The subscriber uses a call back to plot the time stamp for each message to show the timing of processing each message. The initial messages take longer to process, but all the messages are eventually processed from the queue.
% Create a publisher to provide sensor data robotNode = ros2node("/simple_robot"); lidarPub = ros2publisher(robotNode,"/laser_scan","sensor_msgs/PointCloud2",... "History","keeplast","Depth",20); % Create a subscriber representing localization, requiring all scan data hFig = figure; hAxesLidar = axes("Parent",hFig); title("Message Timeline (Keep All)")
localizationSub = ros2subscriber(robotNode,"/laser_scan",... @(msg)exampleHelperROS2PlotTimestamps(msg,hAxesLidar),... "History","keepall"); % Send messages, simulating an extremely fast sensor load robotPoseLidarData.mat lidarScans for iMsg = 1:numel(lidarScans) send(lidarPub,lidarScans(iMsg)) end % Allow messages to arrive, then remove the localization subscriber pause(3) clear localizationSub
In situations where messages being dropped is less important, and only the most up-to-date information really matters, a smaller queue is recommended to improve performance and ensure the most recent information is being used. This example shows quicker processing of the first messages and still gets all the messages. Depending on your resources however, you may see messages get dropped.
% Create a subscriber representing user interface display hFig = figure; hAxesLidar2 = axes("Parent",hFig); title("Message Timeline (Keep Last 1)")
scanDisplaySub = ros2subscriber(robotNode,"/laser_scan",... @(msg)exampleHelperROS2PlotTimestamps(msg,hAxesLidar2),... "History","keeplast","Depth",1); for iMsg = 1:numel(lidarScans) send(lidarPub,lidarScans(iMsg)) end % Allow messages to arrive, then remove the subscriber and publisher pause(3) clear lidarPub scanDisplaySub
Reliability
The Reliability
QoS policy determines whether to guarantee delivery of messages, and has the options:
"reliable"
- The publisher continuously sends the message to the subscriber until the subscriber confirms receipt of the message."besteffort"
- The publisher sends the message only once, and does not confirm that the subscriber receives it.
Reliable
A "reliable"
connection is useful when all of the data must be processed, and any dropped messages may impact the result. This example publishes Odometry
messages and uses a subscriber callback to plot the position. Because for the "reliable"
setting, all the positions are plotted in the figure.
% Create a publisher for odometry data odomPub = ros2publisher(robotNode,"/odom","nav_msgs/Odometry",... "Reliability","reliable"); % Create a subscriber for localization hFig = figure; hAxesReliable = axes("Parent",hFig); title("Robot Position (Reliable Connection)") xlabel("X (m)") ylabel("Y (m)")
odomPlotSub = ros2subscriber(robotNode,"/odom",... @(msg)exampleHelperROS2PlotOdom(msg,hAxesReliable,"ok"),... "Reliability","reliable"); % Send messages, simulating an extremely fast sensor load robotPoseLidarData.mat odomData for iMsg = 1:numel(odomData) send(odomPub,odomData(iMsg)) end pause(5) % Allow messages to arrive and be plotted % Temporarily prevent reliable subscriber from reacting to new messages odomPlotSub.NewMessageFcn = [];
Best Effort
A "besteffort"
connection is useful to avoid impacting performance if dropped messages are acceptable. If a publisher is set to "reliable"
, and a subscriber is set to "besteffort"
, the publisher treats that connection as only requiring "besteffort"
, and does not confirm delivery. Connections with "reliable"
subscribers on the same topic are guaranteed delivery from the same publisher.
This example uses a "besteffort"
subscriber, but still receives all messages due to the low impact on the network.
hFig = figure; hAxesBestEffort = axes("Parent",hFig); title("Message Timeline (Best Effort Connection)")
odomTimingSub = ros2subscriber(robotNode,"/odom",... @(msg)exampleHelperROS2PlotTimestamps(msg,hAxesBestEffort),... "Reliability","besteffort"); for iMsg = 1:numel(odomData) send(odomPub,odomData(iMsg)) end pause(3) % Allow messages to arrive and be plotted
Compatibility
Ensuring compatibility is an important consideration when setting Reliability
. A subscriber with a "reliable"
option set requires a publisher that meets that standard. Any "besteffort"
publishers do not connect to a "reliable"
subscriber because messages are not guaranteed to be delivered. In the opposite situation, a "reliable"
publisher and a "besteffort"
subscriber do connect, but the connection behaves as "besteffort"
with no confirmation when receiving messages. This example shows a "besteffort"
publisher sending messages to the "besteffort"
subscriber already set up. Again, due to the low impact on the network, the "besteffort"
connection is sufficient to process all the messages.
% Reactivate reliable subscriber to show no messages received odomPlotSub.NewMessageFcn = @(msg)exampleHelperROS2PlotOdom(msg,hAxesReliable,"*r"); % Send messages from a best-effort publisher bestEffortOdomPub = ros2publisher(robotNode,"/odom","nav_msgs/Odometry",... "Reliability","besteffort"); for iMsg = 1:numel(odomData) send(bestEffortOdomPub,odomData(iMsg)) end % Allow messages to arrive, then remove odometry publishers and subscribers pause(3) % Allow messages to arrive and be plotted clear odomPub bestEffortOdomPub odomPlotSub odomTimingSub
Durability and Depth
The Durability
QoS policy controls the persistence of messages for late-joining connections, and has the options:
"transientlocal"
- For a publisher, messages that have already been sent are maintained. If a subscriber joins the network with"transientlocal"
Durability
after that, then the publisher sends the persisted messages to the subscriber."volatile"
- Publishers do not persist messages after sending them, and subscribers do not request persisted messages from publishers.
The number of messages persisted by publishers with "transientlocal"
Durability
is also controlled by the Depth
input. Subscribers only request the number of recent messages based on their individual Depth
settings. Publishers can still store more messages for other subscribers to get more. For example, a full list of the robot position may be useful for visualizing its path, but a localization algorithm may only be interested in the last known location. This example illustrates that by using a localization subscriber to display the current position and a plotting subscriber to show all positions in the queue.
% Publish robot location information posePub = ros2publisher(robotNode,"/bot_position","geometry_msgs/Pose2D",... "Durability","transientlocal","Depth",100); load robotPoseLidarData.mat robotPositions for iMsg = 1:numel(robotPositions) send(posePub,robotPositions(iMsg)) pause(0.2) % Allow for processing time end % Create a localization update subscriber that only needs current position localUpdateSub = ros2subscriber(robotNode,"/bot_position",@disp,... "Durability","transientlocal","Depth",1); pause(1) % Allow message to arrive
x: 0.1047 y: -2.3168 theta: -8.5194
% Create a visualization subscriber to show where the robot has been hFig = figure; hAxesMoreMsgs = axes("Parent",hFig); title("Robot Position (Transient Local Connection)") xlabel("X (m)") ylabel("Y (m)") hold on
posePlotSub = ros2subscriber(robotNode,"/bot_position",... @(msg)plot(hAxesMoreMsgs,msg.x,msg.y,"ok"),... "Durability","transientlocal","Depth",20); pause(3) % Allow messages to arrive and be plotted
Compatibility
Similar to Reliability
, incompatible Durability
settings can prevent communication between publishers and subscribers. A subscriber with "transientlocal"
Durability
requires a publisher with "transientlocal"
Durability
. If a publisher is "volatile"
, no connection is established with "transientlocal"
subscribers. If a publisher is "transientlocal"
and the subscriber "volatile
", then that connection is created, without sending persisting messages to the subscriber.
% Reset plotting behavior posePlotSub.NewMessageFcn = @(msg)plot(hAxesMoreMsgs,msg.x,msg.y,"xr"); % Send messages from volatile publisher volatilePosePub = ros2publisher(robotNode,"/bot_position",... "Durability","volatile"); for iMsg = 1:numel(robotPositions) send(volatilePosePub,robotPositions(iMsg)) pause(0.2) % Allow for processing time end
No messages are received by either "transientlocal"
subscriber.
% Remove pose publishers and subscribers clear posePub volatilePosePub localUpdateSub posePlotSub robotNode
Deadline
The Deadline
QoS policy defines the expected interval for publishing consecutive messages to a topic. It sets the duration permitted between messages.
For subscribers, it outlines the permissible duration between message receptions. Coming to publishers, it specifies the allowed duration between message transmissions.
If the user does not set the Deadline
QoS policy, it indicates an unspecified duration. This means that the underlying middleware typically interprets this as an infinitely long duration.
In this example, the publisher is responsible for providing robot position data, while the subscriber is set up to receive and plot this data. The 3-second Deadline
specifies that every succeeding message is published to the /laser_scan
topic within 3 seconds of publishing the preceding message.
% Create a publisher to provide sensor data robotNode = ros2node("/simple_robot"); lidarPub = ros2publisher(robotNode,"/laser_scan","sensor_msgs/PointCloud2", "Deadline",5); % Create a subscriber representing localization, requiring all scan data hFig = figure; hAxesLidar = axes("Parent",hFig); title("Message Timeline (Deadline)")
localizationSub = ros2subscriber(robotNode,"/laser_scan",... @(msg)exampleHelperROS2PlotTimestamps(msg,hAxesLidar),"Deadline",5); % Send messages, simulating an extremely fast sensor load robotPoseLidarData.mat lidarScans for iMsg = 1:numel(lidarScans) send(lidarPub,lidarScans(iMsg)) end % Allow messages to arrive, then remove the localization subscriber pause(2) clear localizationSub
Compatibility
Compatibility must be established while setting the Deadline
QoS policy. A publisher with unset Deadline
policy can connect to a subscriber meeting the same standards only. If a publisher has duration set to an arbitrary value, say "x"
, then it can communicate to a subscriber with the following options:
QoS policy is unset which means that the duartion is equal to an infinite value.
Duration is set to the same arbitrary value
"x"
.Duration is set to a different arbitrary value
"y"
, where"y"
>"x".
Lifespan
The Lifespan
QoS policy defines the maximum duration between publishing and message reception without considering the message as stale or expired. It sets the duration for which a message remains valid.
For subscriptions, it defines the duration a message is deemed valid, beyond which it will not be received. For Publishers, it sets the timeframe a message is considered valid, after which it will be deleted from the topic history and no longer sent to Subscribers.
Messages that have expired are silently discarded. If the user does not set the Lifespan
QoS policy, it indicates an unspecified duration. This means that the underlying middleware typically interprets this as an infinitely long duration.
In this example, the publisher is set up to provide sensor data related to laser scans, and the Lifespan
QoS policy is specifically set to 5 seconds. This means that any message published by the publisher will be considered valid for 5 seconds before it is no longer remains valid.
% Create a publisher to provide laser scan sensor data robotNode = ros2node("/simple_robot"); lidarPub = ros2publisher(robotNode,"/laser_scan","sensor_msgs/PointCloud2",... "Lifespan", 5); % Create a subscriber representing localization, requiring all scan data hFig = figure; hAxesLidar = axes("Parent",hFig); title("Message Timeline (Lifespan)")
localizationSub = ros2subscriber(robotNode,"/laser_scan",... @(msg)exampleHelperROS2PlotTimestamps(msg,hAxesLidar),... "Lifespan", 5); % Send messages, simulating an extremely fast sensor load robotPoseLidarData.mat lidarScans for iMsg = 1:numel(lidarScans) send(lidarPub,lidarScans(iMsg)) end % Allow messages to arrive, then remove the localization subscriber pause(3) clear localizationSub
Liveliness
The Liveliness
QoS policy sets the protocol for entities to declare their level of their liveliness.
For Subscriptions, it determines the reporting standard expected from the Publishers to which they are subscribed. For Publishers, it defines the reporting level they will offer to notify Subscribers that they are alive.
Since this QoS policy does not represent a duration, the default value will utilize the underlying middleware's default setting, configured as "automatic"
. This 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 LeaseDuration
.
Compatibility
A publisher with Liveliness
QoS policy set to "automatic"
can create a compatible connection with a subscriber having "automatic" Liveliness
only.
LeaseDuration
The LeaseDuration
QoS policy defines the maximum duration allowed to a publisher to demonstrate its liveliness before the system considers it to have lost liveliness. Losing liveliness could serve as an indication of failure.
If the user does not set the LeaseDuration
QoS policy, it indicates an unspecified duration. This means that the underlying middleware typically interprets this as an infinitely long duration.
Compatibility
Publishers and subscribers with LeaseDuration
QoS policy follow the same pattern of compatibility for connecting as that of Deadline
QoS policy. A publisher with unset LeaseDuration
policy can connect to a subscriber meeting the same standards only. If a publisher has LeaseDuration
set to an arbitrary value, say "x"
, then it can communicate to a subscriber with the following options:
QoS policy is unset which means that the duartion is equal to an infinite value.
Duration set to the same arbitrary value
"x"
.Duration set to a different arbitrary value
"y"
, where"y"
>"x".
In this example, when any of the publishers has published a message, the system will consider all publishers of the node to be alive for an additional LeaseDuration
of 5 seconds.
% Create a publisher for odometry data with Liveliness QoS policy set to automatic odomPub = ros2publisher(robotNode,"/odom","nav_msgs/Odometry",... "Liveliness", "automatic", "LeaseDuration", 5); % Create a subscriber for localization with Liveliness QoS policy set to automatic hFig = figure; hAxesLiveliness = axes("Parent",hFig); title("Robot Position (Automatic Liveliness)") xlabel("X (m)") ylabel("Y (m)")
odomPlotSub = ros2subscriber(robotNode,"/odom",... @(msg)exampleHelperROS2PlotOdom(msg,hAxesLiveliness,"ok"),... "Liveliness", "automatic", "LeaseDuration", 5); % Send messages, simulating an extremely fast sensor load robotPoseLidarData.mat odomData for iMsg = 1:numel(odomData) send(odomPub,odomData(iMsg)) end pause(5) % Allow messages to arrive and be plotted % Temporarily prevent subscriber from reacting to new messages odomPlotSub.NewMessageFcn = [];