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 mode

• Depth - Message queue size

• Reliability - Delivery guarantee of messages

• Durability - Persistence of messages

• Deadline - Expected interval between consecutive messages

• Lifespan - Message validity window after reception

• Liveliness - Entity aliveness asserting protocol

• LeaseDuration - 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 the Depth 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 = [];