Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท MQTT and Messaging

MQTT Quality of Service: QoS 0, 1 and 2

Understand MQTT delivery guarantees: at most once, at least once and exactly once. Simulate a lossy network and see losses, duplicates and handshakes.

Wireless links lose packets. A sensor on a weak Wi-Fi signal or a cellular connection in a moving truck will occasionally send a message that never arrives. MQTT lets each message choose how hard the system should try, through its Quality of Service (QoS) level. Higher levels cost more packets and more battery, so you pick the cheapest level that is still correct for your data.

The QoS applies per hop: once between the publisher and the broker, and again between the broker and each subscriber. The effective level for a subscriber is the lower of the publish QoS and the QoS the subscriber requested.

The three levels

Three delivery levels

QoS 0 At most once. Fire and forget
QoS 1 At least once. Retries, may duplicate
QoS 2 Exactly once. Four-step handshake

More guarantee means more packets

1 / 2
  • QoS 0, at most once. The sender transmits once and forgets. No acknowledgment, no retry. The message may be lost, never duplicated. Cheapest.
  • QoS 1, at least once. The sender stores the message and sends it with a packet ID until it receives a PUBACK. If the acknowledgment is lost, the sender retransmits and the receiver gets a duplicate.
  • QoS 2, exactly once. A four-message handshake (PUBLISH, PUBREC, PUBREL, PUBCOMP) lets the receiver remember the packet ID until the sender confirms, so the application sees the message once. Slowest and most expensive.
sequenceDiagram
  participant P as Publisher
  participant B as Broker
  P->>B: PUBLISH id=7 (QoS 1)
  B-->>P: PUBACK id=7
  Note over P,B: If PUBACK is lost, P resends PUBLISH id=7 with DUP flag

QoS 1: the publisher keeps the message until the acknowledgment arrives.

Simulating a bad network

We cannot break a real network in the editor, so the example uses a seeded pseudo-random generator: the "link" drops 30% of the packets in each direction. The seed makes the result the same every time.

Node.js QoS 0 versus QoS 1 on a lossy link

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

QoS 0 loses some messages. QoS 1 delivers all of them, but some arrive twice because the acknowledgment was the packet that got lost. This is why QoS 1 handlers must be idempotent: handling the same message twice must be harmless. Setting a heater to ON twice is fine; adding 5 to a counter twice is not.

Exactly once with a handshake

QoS 2 avoids duplicates by splitting the exchange in two phases. The receiver stores the packet ID after the first phase and ignores repeats. The simulator below shows the receiver side: even if the publisher resends the same PUBLISH three times, the application is called once.

Node.js QoS 2 receiver state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing a level in practice

  • Telemetry that is replaced a moment later (temperature every 5 s): QoS 0. A lost reading is not a problem.
  • Commands and alerts (open the door, fire detected): QoS 1 with idempotent handlers.
  • Events that must be counted once (a payment, an inventory change): QoS 2, or QoS 1 with a unique event ID that the receiver deduplicates. Many large deployments prefer the latter because QoS 2 is slower and poorly supported by some cloud brokers (AWS IoT Core, for example, supports only QoS 0 and 1).

A few more facts:

  • A QoS 1 or 2 message to a disconnected persistent subscriber is queued by the broker; see sessions.
  • Every unacknowledged message takes memory on a small device. Limit the number of in-flight messages.
  • QoS is not end-to-end. A QoS 1 publish acknowledged by the broker says nothing about whether a subscriber processed it.

On a real microcontroller the level is a parameter (read-only snippet, needs a broker):

Python
# MicroPython with umqtt.simple
client.publish(b"plant/valve/state", b"closed", retain=False, qos=1)
client.subscribe(b"plant/valve/set", qos=1)

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which QoS level can produce duplicate messages at the receiver?

    At-least-once delivery retransmits when the acknowledgment is missing, so the receiver may see the same message twice.
  2. 2. A publisher uses QoS 2 but the subscriber requested QoS 0. What QoS does the subscriber get?

    Delivery to a subscriber uses the lower of the two levels.
  3. 3. What makes a QoS 1 message handler idempotent?

    Idempotent handlers tolerate duplicates, for example by setting a state instead of incrementing it.
  4. 4. Which level suits a temperature reading sent every five seconds?

    A lost reading is replaced soon by the next one, so the cheapest level is enough.

Summary

  • QoS 0 is at most once, QoS 1 at least once (duplicates possible), QoS 2 exactly once (handshake).
  • The delivered QoS is the minimum of publish QoS and subscription QoS, per hop.
  • Use QoS 0 for frequent readings, QoS 1 plus idempotent handlers for commands, QoS 2 or event IDs for must-count-once events.
  • Higher QoS costs bandwidth, battery and memory.

Next: Retained Messages, Last Will and Sessions