5 MQTT QoS Levels
-
Which messages can be lost, and which cannot?
5.1 Start With The Consequence Of Losing One Message
Choose the Promise for One Message Family
Picture a cold room that sends routine temperatures and a rare warm alarm. Losing one routine value may be acceptable. Losing or repeating the alarm may change a safety decision. Those two message families should not inherit a promise by accident.
Telemetry means readings and status sent by a remote device. Message Queuing Telemetry Transport (MQTT) means a lightweight way for devices to exchange messages. A protocol means shared rules for that exchange. A broker means the service that passes messages from senders to receivers. A payload means the useful data inside one message. Quality of service means the delivery promise chosen for a message; it is called QoS.
Send both families, then cut the link, repeat an acknowledgement, restart the broker, and reconnect the receiver. Record losses, repeats, delay, and the final cold-room state. Choose the weakest promise that still protects the decision.
This runway does not guarantee a physical response or prove the whole path. The deeper sections explain each QoS flow, stored session state, duplicates, and the evidence needed for a release choice.
QoS is not a badge for the whole system; it is a decision for each message family. A replaceable temperature sample can disappear with little harm, a door-open alert should arrive at least once, and a narrow audit command may need duplicate control. Begin with the consequence of loss or duplication, then choose the smallest MQTT QoS that matches it.
5.2 QoS Is a Message-Family Decision
MQTT Quality of Service controls how hard the protocol tries to deliver a message between a client and the broker. It is not a single setting for an entire device. A useful IoT design chooses QoS per message family: frequent telemetry, important events, commands, retained state, and workflow acknowledgements may all need different handling.
The tradeoff is reliability evidence versus overhead. Higher QoS adds acknowledgement state and retry behavior. That can be exactly what an alarm or command needs, but it is often wasteful for replaceable sensor readings where the next value arrives soon.
Broker Bex
“A message with no subscriber is a tree falling in an empty forest — design the topic before the payload.”
In this chapter, Bex prices each guarantee on the board: what the acknowledgement costs, and who is still subscribed when the retry finally lands.
Start the decision with consequence, not protocol vocabulary. If a dropped value is replaced by the next sample and the dashboard can show freshness, QoS 0 keeps radios quiet and broker state small. If a door-open event or threshold crossing must reach a workflow but can be deduplicated with an event id, QoS 1 is usually the practical middle. If a duplicate protocol delivery would be harmful, first redesign the message as a desired-state command; only then consider QoS 2 for a narrow family with a clear audit need.
If you only need the intuition, this layer is enough: use QoS 0 for replaceable telemetry, QoS 1 for important events that can tolerate duplicates, and QoS 2 only when duplicate protocol delivery would be unsafe and cannot be handled by idempotent design.
Write that decision into topic documentation. For example, site/+/temperature can state "QoS 0, max staleness 30 seconds", while site/+/alarm/open can state "QoS 1, event id required". The label keeps firmware, broker policy, and dashboard expectations aligned.
The Three Contracts
QoS 0: At Most Once
The message is sent without a protocol acknowledgement. This fits high-rate, replaceable telemetry where occasional loss is acceptable.
QoS 1: At Least Once
The sender keeps state until an acknowledgement arrives. Delivery is retried, so the receiver must tolerate possible duplicates.
QoS 2: Exactly Once
The sender and receiver use a multi-step handshake to avoid protocol-level duplicates. Use it sparingly because it adds state and round trips.
Bex’s Topic Board
Topic: Topic documentation states the promise — site/+/alarm/open declares “QoS 1, event id required.” QoS: Each step up buys acknowledgement state and retries; the QoS 2 handshake adds round trips. Subscriber: An at-least-once receiver meets the same event twice — deduplication is its job, not the broker’s.
Beginner Examples
These examples connect QoS choices to the effects of loss and duplicate delivery. A temperature reading published every few seconds is usually QoS 0; the next reading replaces a lost one. A door-open event is often QoS 1 because the event matters. Event IDs or idempotent processing can handle duplicates. A non-idempotent command should first be redesigned as a safe state-setting command. If duplicate execution is still unsafe, QoS 2 may be justified.
Overview Knowledge Check
If this is enough, stop with the message-family rule. Continue to Practitioner when you need to document a selection record for a real fleet.
5.3 Write the QoS Selection Record
The practical workflow is to list each message family, decide what failure is tolerable, and record the protocol and application evidence that will prove the design works. A blanket "QoS 1 everywhere" or "QoS 2 for critical systems" rule hides too many edge cases.
For each row, include the retry horizon and the application outcome. A QoS 1 command with a command id and final state readback can be safer than a QoS 2 toggle with no idempotency. A retained status message may need QoS 1 when subscribers depend on it after reconnect, while a high-rate diagnostic stream may stay QoS 0. The record should also name what the broker is allowed to queue for offline subscribers and how long stale messages remain useful.
Fleet Selection Record
set_fan_state=on.Practitioner Checks
Separate protocol delivery from outcome
MQTT QoS proves a broker/client delivery step. It does not prove that a pump started, a door locked, or a technician responded.
Design for duplicates
QoS 1 is common in production because duplicates can be handled with event IDs, desired-state commands, and idempotent consumers.
Review offline behavior
Persistent sessions, retained state, broker limits, and client reconnect behavior decide what happens while subscribers are offline.
Practitioner Knowledge Check
The selection record should end with a test plan: disconnect a client, drop an acknowledgement, replay a duplicate, restart a subscriber, and verify that the application outcome still matches the message-family promise.
5.4 QoS Is Hop-by-Hop State
MQTT QoS is negotiated and enforced on each delivery leg. A publisher can send to the broker at one QoS, while a subscriber receives at a different effective QoS depending on its subscription and broker behavior. The broker is not just forwarding bytes; it may store state, retry, downgrade delivery, or queue messages for a persistent session.
This is why QoS should not be described as end-to-end business confirmation. A broker acknowledgement is not the same as application handling. Critical workflows still need an application-level acknowledgement, audit record, or state readback.
One practical test is to drop the network after each acknowledgement boundary and inspect what happens on reconnect. For QoS 1, the duplicate path should be visible through the DUP flag and through application deduplication logs. For QoS 2, the broker and client should resume the packet-id handshake instead of executing the action twice. Those traces make the distinction between protocol delivery and physical outcome concrete.
5.4.1 Sequence Views
To compare the three delivery contracts without confusing them with application outcomes, begin with Figure 5.1. It establishes the minimum state against which the acknowledgement-based flows can be read.
Read Figure 5.1 from publisher to broker. There is one PUBLISH and no return packet, so the sender gains no protocol evidence that this delivery leg completed. That low-state baseline explains why QoS 0 suits replaceable telemetry but cannot support a must-arrive claim by itself.
Next inspect Figure 5.2 to see exactly where at-least-once delivery adds state and where duplicate handling becomes an application responsibility.
Follow Figure 5.2 from PUBLISH to PUBACK, then trace the retry path when that acknowledgement is lost. The packet identifier keeps the exchange recognizable, but a repeated PUBLISH can still reach the receiver. This is why the running design record pairs QoS 1 with idempotent handling or explicit deduplication.
Finally inspect Figure 5.3 to locate the extra handshake state that prevents the receiver from presenting the same publication twice on one MQTT delivery leg.
Read Figure 5.3 in four stages: PUBLISH transfers the publication, PUBREC records receipt, PUBREL advances the transaction, and PUBCOMP closes it. Both peers retain packet-identifier state until completion. The extra protocol certainty costs packets, storage, and recovery logic, and it still stops at the MQTT boundary rather than proving that a physical action occurred.
-
Send the message. Keep its packet number.
-
The broker records that it got the message.
-
The sender returns a release packet.
-
The broker closes the exchange. Both sides clear the saved state.
-
Now check the device result. Packet proof is not action proof.
What the Broker Must Remember
QoS 0: The broker routes messages to current matching subscribers without acknowledgement state for that publish. QoS 1: The sender and receiver track a packet identifier until acknowledgement, and the receiver must handle possible redelivery. QoS 2: Both sides track a handshake until completion, reducing duplicate protocol delivery but increasing state and timing sensitivity. Persistent sessions: Offline behavior depends on session configuration, queued-message policy, retained messages, and broker limits, not just the publish QoS. Application outcomes: A device should publish a separate result or state update when the business outcome matters.
Bex’s Topic Board
Topic: One topic can have many delivery strengths because each subscription sets its own effective QoS. QoS: QoS 1 holds a packet identifier until acknowledged; QoS 2 keeps a two-sided handshake open. Subscriber: A persistent session queues messages for an offline subscriber — within broker limits, silence costs storage.
For a critical command, a strong evidence chain has two acknowledgements: MQTT-level delivery to the broker path, and application-level proof that the device accepted or rejected the requested state.
Under-the-Hood Knowledge Check
The under-the-hood review is complete when you can explain what state exists at the publisher, broker, subscriber, and application outcome boundary for each message family.
5.5 Figure Review: QoS as a Packet Ledger
Compare QoS levels by the packets and retained state they require, not by treating the number as a generic quality score.
Figure 5.4 contrasts QoS 0 · AT MOST ONCE with the PUBLISH id=42 → PUBACK id=42 evidence of QoS 1 and the four-packet QoS 2 exchange; the Retained message ≠ handshake state callout prevents two different broker obligations from being conflated.
5.6 Choose QoS for a Valve Command and a Gauge
For this MQTT QoS choice, a pressure gauge sends a fresh value every second, while a valve receives one rare OPEN command. Figure 5.1 shows a one-way PUBLISH with no acknowledgement. Figure 5.2 adds PUBACK and allows duplicate delivery. Figure 5.3 adds the longer handshake used to avoid duplicate application delivery. Figure 5.4 keeps packet identifier 42 and its handshake state apart from a retained message.
In the message-family contract, if a gauge sends 60 readings per minute, losing one QoS 0 reading may be acceptable because the next arrives one second later. Repeating an OPEN action under QoS 1 can be unsafe unless the valve application treats a command identifier as idempotent. QoS 2 reduces duplicate delivery at the MQTT layer, but it costs more packets and stored session state.
5.6.1 Predict the MQTT QoS Outcome
Measure the full exchange on the chosen link. QoS 2 uses more handshake steps than QoS 1, so a weak radio can spend longer awake. The stronger delivery contract may still fit a rare valve command while wasting energy on frequent gauge samples.
Packet identifier reuse also follows session state. Identifier 42 can be used again after its QoS exchange finishes, but using it for two unfinished exchanges would confuse acknowledgements. A reconnect can change what the broker retains, depending on the MQTT session settings. Device tests must cover the chosen clean-start and expiry behaviour.
- Predict: A QoS 1 PUBACK is lost, so PUBLISH id 42 is sent again. May the subscriber see the payload twice? Check: Yes. At-least-once delivery permits a duplicate and the application must handle it.
- Predict: A retained QoS 0 state is stored by the broker. Does “retained” upgrade its handshake to QoS 2? Check: No. Retention and MQTT delivery QoS are separate choices.
5.7 Summary
MQTT QoS levels are delivery contracts, not global device quality settings. QoS 0 minimizes acknowledgement overhead for replaceable telemetry. QoS 1 adds delivery acknowledgement but requires duplicate-safe consumers. QoS 2 adds a stronger protocol handshake for narrow cases where duplicate protocol delivery is unsafe.
The most reliable design is usually a mix: QoS 0 for frequent state, QoS 1 for important events and idempotent commands, and application-level acknowledgement wherever a physical or business outcome must be proven.
5.8 Key Takeaway
Choose MQTT QoS per message family, then prove the outcome separately. Broker delivery evidence is useful, but it is not the same as device action, human response, or business completion.