MQTT QoS Reference
More
Depth: Practitioner
Progress saves as you read. Mark sections complete as you go; your progress appears in the sidebar.
This commentary accompanies the figures in MQTT QoS Levels. Return there to follow the boiler-sensor house through the delivery choices.
Vocabulary
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.
Reading the decision chart
Start at the top of the chart with one message. If losing it is acceptable, follow the path to QoS 0. If loss is not acceptable, ask whether the receiver can handle a repeat. The chart points to QoS 1 when it can and QoS 2 when it cannot. Use this as a starting point for the selection record in the chapter. Also check the application outcome and the cost of each flow before choosing a policy.
Reading the packet sequences
To compare the three delivery contracts without confusing them with application outcomes, begin with the QoS 0 sequence. It establishes the minimum state against which the acknowledgement-based flows can be read.
Read the QoS 0 sequence from the publisher to the broker. The one arrow is a PUBLISH packet. This leg has no return packet to confirm receipt. If a packet is lost, this flow does not retry it. The sender has no protocol proof that the leg completed. This simple flow suits a stream of readings when the next value can replace a lost one. It cannot, by itself, support a claim that a message must arrive.
Next inspect the QoS 1 sequence to see exactly where at-least-once delivery adds state and where duplicate handling becomes an application responsibility.
Follow the QoS 1 sequence from PUBLISH to PUBACK, the packet that confirms receipt. Now trace a lost reply followed by a reconnect that resumes the session. The sender resends the unfinished PUBLISH with the same packet identifier. MQTT 5 permits this retry only when the session resumes. The receiver may therefore see the message twice. A design using QoS 1 needs a way to handle that repeat. For example, an event ID can help the receiver spot a copy, or a state-setting command can have the same effect when repeated.
Finally inspect the QoS 2 sequence to locate the extra handshake state that prevents the receiver from presenting the same publication twice on one MQTT delivery leg.
Track one packet identifier. Watch both handshakes finish. Read the QoS 2 sequence 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, allowing retransmission without presenting the publication twice on that MQTT leg. The extra certainty costs four packet steps, durable exchange state, and recovery logic. This exchange ends at the broker’s MQTT boundary: an app receipt or a device state check must still prove that a database saved the data or a physical action took place.
Protocol and device evidence
Follow the five panels from the send to the final device check. The first four show the packet exchange and the state held while it runs. The last panel crosses the boundary to the device result. A completed exchange tells you about the MQTT leg; it does not show that a device carried out the request. For a command that matters, look for a separate reply or a state report from the device as well.
Packet ledger and command choices
Each QoS level uses a different packet flow. A packet is a unit of data sent on the network. The sender and receiver may also keep state: a record of an exchange that is still in progress. Compare the flows and records in the chapter to see what each level costs.
Read the packet ledger from top to bottom. QoS 0 sends PUBLISH with no reply. QoS 1 adds PUBACK. After a lost reply, a retry on session resumption can cause a duplicate. QoS 2 uses four packet steps and keeps a record of the exchange until it ends. The packet ID helps track that exchange. The callout makes one more distinction: a retained message is separate from handshake state. One is saved for subscribers; the other tracks an active exchange.
A pressure gauge sends one fresh value each second. A valve gets one rare OPEN command. Start with the QoS 0 sequence: one PUBLISH has no reply. In the QoS 1 sequence, PUBACK confirms receipt, but a repeat may arrive. In the QoS 2 sequence, a longer exchange prevents repeats on that MQTT leg. The packet ID in the packet ledger tracks the exchange. It is separate from a retained message.
A lost gauge value may be safe because a new one follows. A repeated OPEN command may be unsafe. Give each command an app ID and check whether it was already handled. An idempotent command has the same effect when repeated. QoS 2 adds packets and state; it does not prove that the valve acted once.
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.
Selection record source notes
These notes expand the chapter’s selection record. The assessment headings in the preserved source excerpts refer to the standalone QoS check.
Reference: Message families and delivery contracts
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.
If a reading is lost or an alert arrives twice, which QoS fits each message family?
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 with no protocol reply. Use this for frequent readings when the next value can replace one that is lost.
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.
Topic board
- Topic: Topic documentation states the promise —
site/+/alarm/opendeclares “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.
Reference: Selection records and duplicate handling
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 deployed systems. Event IDs can help detect repeats. Commands can set a desired state. A receiver can also be idempotent: repeating the same request leaves the same result.
Review offline behavior
What happens while a receiver is offline depends on several things. Check persistent sessions and retained state. Also check broker limits and what the client does when it reconnects.
Practitioner Knowledge Check
End the selection record with a test plan. Disconnect a client and drop a reply. Send a repeat and restart a subscriber. Check that the app result still meets the promise for that kind of message.
Reference: Broker state and device evidence
What the Broker Must Remember
QoS 0: The broker sends to current matching subscribers. It keeps no reply state for that publish. QoS 1: Both peers track a packet ID until the reply arrives. The receiver must handle repeats. QoS 2: Both peers track a handshake until it ends. This prevents duplicate delivery on that MQTT leg. It adds state and makes timing more important. Persistent sessions: Offline behavior depends on session settings, queue policy, retained messages, and broker limits. Publish QoS alone does not decide it. App results: When the business result matters, the device should send a separate result or state update.
Topic board
- Topic: One topic can have many delivery strengths. Each subscription sets its own effective QoS.
- QoS: QoS 1 holds a packet ID until the reply arrives. QoS 2 keeps a handshake open on both sides.
- Subscriber: A persistent session queues messages while a subscriber is offline. Broker limits still apply. The queue needs storage.
For a critical command, seek two kinds of proof. First, check MQTT delivery on the broker path. Then check the app reply. It should show whether the device accepted or rejected the requested state.
Under-the-Hood Knowledge Check
For each kind of message, explain which records each part keeps. Check the publisher, broker, and subscriber. Then explain what proves the app result.
Further MQTT topics
For the architectural, topic and security context behind those records, keep these supporting pages nearby.
