# Mqtt Knowledge Patch > MQTT - Skill: `nevaberry/mqtt-knowledge-patch` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add nevaberry/mqtt-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/mqtt-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/mqtt-knowledge-patch --- # MQTT Compatibility Guidance Use this skill when implementing, reviewing, debugging, or testing MQTT 5.0 or MQTT-SN 2.0 protocol behavior. Start by identifying which protocol is on the wire: their packet layouts, connection abstractions, retry rules, aliases, and error handling are different. ## Reference index | Reference | Topics | | --- | --- | | [MQTT 5 wire format](references/mqtt5-wire-format.md) | Canonical Variable Byte Integers, property encoding and registry, packet-scoped failure codes, WebSocket transport | | [MQTT 5 connections and publishing](references/mqtt5-connections-publishing.md) | CONNECT/CONNACK defaults, Will timing, pipelining, diagnostics, aliases, expiry, Receive Maximum, acknowledgments | | [MQTT 5 subscriptions and operations](references/mqtt5-subscriptions-operations.md) | Shared subscriptions, Subscription Identifiers, retransmission and ordering, request/response, redirection, authentication, protocol errors | | [MQTT-SN packets](references/mqtt-sn-packets.md) | 1.2 migration, framing, registries, identifiers, CONNECT/CONNACK, publish and subscription packets, encapsulation | | [MQTT-SN sessions and topics](references/mqtt-sn-sessions-topics.md) | Sessions and Virtual Connections, PUBWOS, retries, flow control, topic aliases, retained delivery, discovery | | [MQTT-SN authentication, sleep, and protection](references/mqtt-sn-auth-sleep-protection.md) | Authentication profiles, client states, sleeping delivery, security profiles, protection schemes and nonces | ## First distinguish MQTT from MQTT-SN - Treat MQTT 5 Network Connections and MQTT-SN Virtual Connections as different lifecycles. - Decode MQTT Remaining Length and properties with MQTT's canonical base-128 Variable Byte Integer rules. - Decode MQTT-SN Length as either the short one-byte form or the extended `0x01` plus unsigned big-endian 16-bit form. - Do not apply MQTT timeout retransmission behavior to MQTT-SN. MQTT 5 resends QoS flows only across a qualifying reconnect; MQTT-SN defines retry timers and retry limits for selected request packets. - Keep MQTT Topic Aliases scoped to one direction of one Network Connection. Keep MQTT-SN Predefined and Session Topic Aliases in independent namespaces. ## Breaking MQTT-SN 1.2 assumptions For MQTT-SN 2.0 work, remove these 1.2-era assumptions: - Use Topic Alias, Packet Identifier, and Packet Type instead of Topic Id, Message Id, and Message Type. - Carry Will data in CONNECT; do not implement the old Will Message control-packet exchange. - Do not expect a response to DISCONNECT. - Do not use Short Topic Name for ordinary 2.0 PUBLISH. - Accept both short and extended packet Length encodings. - Use protocol version byte `0x02` in CONNECT. - Use the new contiguous Packet Type registry; legacy numeric values are not interchangeable. Optional MQTT-SN 1.2 QoS −1 PUBLISH compatibility is a PUBWOS-equivalent extension, not an ordinary 2.0 publish flow. Read [MQTT-SN sessions and topics](references/mqtt-sn-sessions-topics.md) before accepting it. ## MQTT 5 correctness rules ### Never retransmit on an acknowledgment timer On an established MQTT Network Connection, do not resend QoS 1/2 PUBLISH or PUBREL because a timer expired. Resend after reconnect only when Clean Start is `0` and the Session is present, preserving original Packet Identifiers and required ordering. ### Apply omission defaults field by field Do not treat absent CONNECT or CONNACK properties uniformly: - Session Expiry defaults to `0` on CONNECT and to the CONNECT value on CONNACK. - Receive Maximum defaults to `65535`. - Topic Alias Maximum defaults to `0`. - Maximum QoS defaults to `2`. - Retain, wildcard, Subscription Identifier, and shared-subscription availability default to enabled. - Server Keep Alive defaults to the CONNECT Keep Alive. - Request Problem Information defaults to `1`. Read the full table in [MQTT 5 connections and publishing](references/mqtt5-connections-publishing.md). ### Track flow-control completion precisely Receive Maximum counts only unfinished QoS 1/2 PUBLISH flows. Free a QoS 1 slot at PUBACK. Free a QoS 2 slot at PUBCOMP or at a failing PUBREC with reason at least `0x80`; a successful PUBREC does not free it. A full window does not block non-PUBLISH packets. ### Keep aliases directional A nonempty Topic Name plus Topic Alias establishes or replaces the mapping. An empty Topic Name may reuse only a mapping already established in that direction. Never retain the mapping across a Network Connection. ### Scope errors to their legal packets Validate property identifiers, property value types, and Reason Codes against the containing packet. Before a successful CONNACK, report a connection failure with CONNACK, never DISCONNECT. A Malformed Packet or Protocol Error closes only the affected Network Connection. ## MQTT-SN correctness rules ### Separate Session and Virtual Connection A Session belongs to a Client Identifier and may span multiple Virtual Connections. A Virtual Connection begins with CONNECT and can be deleted by Keep Alive timeout, Retry timeout, DISCONNECT, or a protocol error. Retain Session State while any Virtual Connection exists and until Session expiry after the last one is deleted. Retained messages are not Session State. In-flight QoS 1/2 flows, Session Topic Aliases, subscriptions, queued messages, Will data, and expiry state are. ### Enforce one outstanding request per direction Each Virtual Connection direction permits at most one unacknowledged request across QoS 1/2 PUBLISH, PUBREC, PUBREL, REGISTER, SUBSCRIBE, UNSUBSCRIBE, PINGREQ, SLEEPREQ, and AUTH. A different Packet Identifier while one is outstanding requires DISCONNECT `0x93` and Virtual Connection deletion. A retry of the same request and interleaved PUBWOS remain allowed. ### Retry only eligible packets - Either peer may retry REGISTER, QoS 1/2 PUBLISH, and PUBREL. - Only Clients may retry SUBSCRIBE, UNSUBSCRIBE, SLEEPREQ, and PINGREQ. - Never retry CONNECT or AUTH. - Make a retransmission packet-identical. Reapply Protection Encapsulation when the original used it, although the new envelope may differ. - Delete the Virtual Connection after the maximum retries plus one further Retry Interval without a response. ### Respect reconnect recovery With Clean Start `0` and an existing Session, both peers resend unacknowledged QoS 1/2 PUBLISH and PUBREL with original Packet Identifiers. Do not resend QoS 0. Stop retrying after a PUBACK or PUBREC failure reason of at least `0x80`; set DUP on a resent QoS 2 PUBLISH. ### Validate packet-size boundaries MQTT-SN supplies no fragmentation or reassembly. Configure the transport so a packet arrives complete and unaltered, and for UDP prefer an MTU larger than the largest packet in use. Enforce the CONNECT Maximum Packet Size negotiated for Server-to-Client traffic. ### Treat protection as end-to-end The originator named by Sender Identifier performs Protection Encapsulation. Do not delegate that protection to a Forwarder. Once an endpoint uses a shared key with a peer, protect every MQTT-SN packet exchanged with that peer. ## Implementation workflow 1. Identify MQTT 5 versus MQTT-SN before parsing the fixed header. 2. Model Session state separately from transport or connection state. 3. Build packet-specific tables for fields, properties, identifiers, defaults, Reason Codes, and permitted directions. 4. Make malformed, protocol-error, and negative-acknowledgment paths explicit; do not funnel every failure through DISCONNECT. 5. Track QoS state transitions and identifier ownership per sending peer. 6. Test reconnect recovery separately from same-connection operation. 7. Test aliases in both directions and across connection teardown. 8. For MQTT-SN, test Active, Asleep, Awake, Disconnected, and None server-side states independently. 9. For WebSocket transport, feed arbitrary frame splits and multiple MQTT packets per binary frame into a streaming decoder. 10. For protected MQTT-SN traffic, test envelope flag combinations, tag sizes, monotonic counters, nonce derivation, and Forwarder nesting. ## Review checklist - Does every Variable Byte Integer use its shortest encoding? - Are property and Reason Code registries packet-scoped? - Are Packet Identifiers allocated, echoed, and released at the correct state transition? - Are QoS windows independent of non-PUBLISH traffic? - Are Will publication, Session expiry, and takeover evaluated together? - Are overlapping and shared subscriptions handled with their distinct delivery rules? - Is re-authentication traffic behavior correct for the selected protocol? - Are MQTT-SN alias namespaces and directional REGISTER/REGACK forms separate? - Do sleep transitions suspend Keep Alive and bound the Awake delivery phase? - Does every terminal error close only the intended Network or Virtual Connection and preserve or discard Session State as specified?