Choose QoS based on delivery requirements: QoS 0 (at most once, fire-and-forget) for high-frequency sensor data where occasional loss is acceptable; QoS 1 (at least once) for critical readings that must arrive even if duplicated; QoS 2 (exactly once) for commands where duplicate execution causes harm
For retained messages, publish with the retained flag set to true on a status or last-known-value topic; new subscribers immediately receive the retained message without waiting for the next publish; clear a retained message by publishing an empty payload with retained=true to the same topic
Configure Last Will and Testament (LWT) in the CONNECT packet: set willTopic, willMessage (e.g., {"status":"offline"}), willQoS, and willRetain; the broker publishes this automatically on unclean disconnect
Pair LWT with a retained online message: on successful connect, immediately publish {"status":"online"} with retained=true to the status topic to overwrite any prior LWT; this creates a reliable online/offline indicator
Understand broker-side QoS downgrade: if a subscriber subscribes at QoS 0 but a message was published at QoS 1, the broker delivers it at QoS 0 — the effective QoS is the minimum of publisher and subscriber QoS
For constrained devices, prefer QoS 1 over QoS 2: QoS 2 requires four-step handshake (PUBLISH, PUBREC, PUBREL, PUBCOMP) which doubles round-trips and increases RAM usage for in-flight message state
Known gotchas
QoS 1 re-delivery of duplicate messages is the client's responsibility to handle idempotently; blindly processing every PUBLISH can cause double-counting in analytics pipelines downstream
A retained message persists on the broker indefinitely until explicitly cleared; forgotten retained messages from decommissioned devices can confuse new subscribers and appear as ghost devices in dashboards
LWT is only sent on unclean disconnect (network drop, crash); a clean DISCONNECT packet suppresses LWT — if a device disconnects gracefully but the application considers it offline, add application-level heartbeats rather than relying solely on LWT
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp