Configure MQTT QoS levels and retained messages for IoT devices
domain: mqtt.org · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Choose QoS level when publishing and subscribing: QoS 0 (at most once, no ack), QoS 1 (at least once, ack required), QoS 2 (exactly once, four-step handshake)
Publish a retained message by setting the retain flag to true; the broker stores the last retained message per topic and delivers it to new subscribers immediately on connect
Set a clean session (clean_start in MQTT v5) to false for persistent sessions; the broker queues QoS 1/2 messages for offline subscribers and delivers on reconnect
Configure a Last Will and Testament (LWT) message on the client connect to notify others when a client disconnects ungracefully
Use topic hierarchies (sensor/room/temperature) and wildcard subscriptions (+ for single level, # for multi-level) to organize and route messages
Known gotchas
QoS 2 requires four network round trips per message; high-frequency IoT telemetry is rarely worth the overhead — prefer QoS 1 with idempotent processing
Retained messages persist until explicitly cleared by publishing an empty payload to the same topic with retain=true; stale retained values can mislead new subscribers
MQTT broker implementations vary in their handling of QoS downgrades: if a publisher sends QoS 2 but a subscriber subscribes at QoS 0, the broker delivers at the lower QoS
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?