MQTT 3.1.1 vs MQTT 5.0: Settings, Differences, and Tests

Switch a client from MQTT 3.1.1 to 5.0 on the same Broker and port, and it may not connect any faster. What changes is how precisely it can express its needs: how long a disconnected session should survive, when a message becomes stale, how many reliable messages it can receive without acknowledging them, and whether a brief connection interruption should immediately notify other devices.

In this guide, V3 means MQTT 3.1.1 and V5 means MQTT 5.0. Mqttable also offers 3.1 for systems explicitly requiring the older protocol. The client, Broker, and listener policy must support the chosen version. TCP, TLS, WebSocket, and port numbers do not determine that version.

Differences at a glance

These additions do not replace publish/subscribe. Topic, QoS, Retain, username/password, and basic Wills already exist in 3.1.1. MQTT 5 Appendix C summarizes new features and some intended uses. The device, bridge, and command examples here are engineering interpretations, not a history of standards-committee decisions.

New Client: identity, version, and credentials

Choose a Broker in Connections, then open New Client / Add client. The Broker row identifies the endpoint this client belongs to. Host, Port, transport, TLS, and certificates are Broker settings, not new MQTT 5 properties. The laboratory endpoints below bind only to loopback; use your organization's endpoint and trusted credentials for real deployments.

Name stays inside the app, Client ID identifies the session, credentials do not encrypt transport, and the version is independent of the port.

Name, Client ID, and their generation buttons

Two connections using the same Client ID on the same Broker can cause the newer connection to take over the older one. Session recovery needs a stable Client ID. Disabling Clean Start while generating a different ID each time cannot recover the old session. MQTT 5 can also return a server-assigned identity; the generation button does not imply that it uses that mechanism.

MQTT version and Authentication Method

Mqttable currently exposes this selector under 5.0. Under 3.x it is hidden, while Username and Password remain available. At protocol level, a Broker supporting JWT can accept it in a 3.1.1 Password field. The location of JWT Tools in the V5 form does not make JWT a V5 feature.

The V5 addition is enhanced authentication, including a method, authentication data, and AUTH packets. Challenge-response need not transmit the original secret as CONNECT Password, and the protocol permits reauthentication within an existing connection. SCRAM does not replace TLS, and protocol support does not prove Mqttable has a button for initiating reauthentication. See the authentication guide and EMQX SCRAM configuration.

Password and JWT are not V5-only; the SCRAM method must match at both endpoints.

Username, Password, and Saved SecretRef

Username and Password start empty. Enter the credentials required by the policy when using Password or SCRAM. None sends no password, even if an old saved value exists. The Password field is bounded by MQTT's two-byte length, at most 65,535 bytes; this is not a suggested password length and does not override provider restrictions.

Only synthetic laboratory credentials are used here. Screenshots do not expose passwords, signing keys, or usable token text. Never place production credentials in User Properties, Topics, payloads, screenshots, or an article.

The Runtime resolves the reference; it is not an MQTT property or a password string transmitted to the Broker.

JWT Tools: algorithms, keys, claims, Encode, and Preview

JWT Tools is a Mqttable utility. None of these controls is an MQTT packet field.

Whether Username, Client ID, subject, or another claim must match is a Broker policy. MQTT does not require them to be the same string.

The synthetic token is generated and masked; Broker acceptance is not implied.

Changing algorithm does not generate a key or verify the existing token.

Sessions, keepalive, and connection properties

Clean Session and Clean Start do not mean automatic reconnect

With MQTT 3.1.1 Clean Session=1, an old session is discarded and the new session is not retained after disconnect. With 0, the Broker attempts recovery and retains state afterward. State includes subscriptions and incomplete QoS 1/2 delivery. Retained messages are not part of an individual client's session.

In MQTT 5, Clean Start only decides whether to discard an old session at connection time. Session Expiry Interval controls retention after disconnect. The current New Client defaults to the cleanup flag enabled.

Why separate the controls? The V3 flag combines "where should this connection start?" and "how long should later state survive?" It cannot express "start from scratch now, but retain this new session for one minute." V5 permits a recovery window without indefinitely retaining sessions for devices that never return.

Session Expiry Interval

Units are seconds, with a protocol range of 0 to 4,294,967,295. Omission defaults to 0. Zero ends the session after disconnect; the maximum means no time-based expiry at protocol level, still subject to Broker resource and administrative policies. The current New Client defaults to 0 and omits the property.

For offline QoS 1/2 recovery, use a stable Client ID, Clean Start off, and a deliberate positive interval. The experiment uses a two-second interval and checks CONNACK Session Present after a longer observation window. A restored UI subscription list is insufficient: Mqttable can restore configured subscriptions automatically. Check Session Present and queued messages to distinguish Broker recovery from local resubscription.

Keep Alive

Units are seconds, range 0 to 65,535, with a current product default of 300. Zero disables MQTT Keep Alive. When there are no other MQTT control packets to send, PINGREQ/PINGRESP checks connection liveness; the Broker handles timeout under the protocol. It does not require a business message every interval, and is not a subscription or message lifetime.

Keep Alive exists in both versions. V5 adds Server Keep Alive, allowing CONNACK to state the value the client should use. Shorter intervals generally detect disconnection sooner but add traffic and device wakeups. Choose based on power, connectivity, and Broker policy rather than a universal best number.

Request Problem Info

The wire value is 0 or 1, with a specification default of 1 when omitted. In the locally fixed Mqttable, the default unchecked control explicitly sends 0; checked sends 1. An absent or nil field remains omitted.

One allows Reason String and User Properties in packets where permitted, but does not require the Broker to provide them. Zero restricts some packets' additional information. It does not disable reason codes or prohibit information permitted in PUBLISH, CONNACK, or DISCONNECT. Reason String is not a stable machine-readable interface.

V5 makes diagnosis more useful while letting small clients express a budget for extra strings and metadata. This control is not a sensitive-data filter.

Request Response Info

The value is 0 or 1, defaulting to zero when absent. The current default is off, which omits the property. Enabling it asks for Response Information in CONNACK, but the Broker may still omit it.

It can help a requester construct response Topics alongside the PUBLISH Response Topic and Correlation Data properties. It does not subscribe to a response Topic, turn every publish into a request, or make the Broker execute a response. V3 applications must arrange these conventions outside those standard fields.

Quotas and User Properties: advertise the receiving budget

Receive Max: outstanding QoS 1/2 messages

The range is 1 to 65,535; zero is invalid. Omission defaults to 65,535. The initial Mqttable field is empty: its 65535 placeholder does not mean the property is already being sent.

In CONNECT, the client advertises the maximum outstanding QoS 1/2 PUBLISH messages it accepts from the Broker. The CONNACK value limits the opposite direction. It does not limit QoS 0 or specify messages per second.

V3 implementations can configure local in-flight limits and Broker policies, but cannot advertise this standard field to each other. V5 lets the sender pause new reliable messages at the receiver's limit. The auxiliary test receiver deliberately withholds PUBACK: with a window of two it does not receive all four messages before acknowledging, and one acknowledgement releases another message.

Maximum Packet Size includes the whole MQTT packet

The property is a positive four-byte integer; zero is invalid. Omission adds no receiver size restriction beyond protocol encoding, implementation, and resource limits. Mqttable starts with an empty field; entering 0 means omit the property, not send an illegal zero.

CONNECT states the client's receiving limit, including Topic, Packet Identifier, properties, and payload. CONNACK states the Broker's receiving limit. A 100-byte payload is not necessarily a 100-byte PUBLISH.

This gives small devices a defined memory budget before an oversized message is transmitted. The Broker must not forward a packet larger than the client's limit. A sender's PUBACK does not prove a constrained subscriber received it. In the test, a 128-byte limit prevented forwarding a 512-byte payload; successful small messages before and after were the controls.

Topic Alias Max: how many mappings the peer may use

The range is 0 to 65,535, default zero if absent. The initial field is empty; zero permits no aliases. CONNECT advertises accepted Broker-to-client aliases. A publishing client's client-to-Broker allowance comes from CONNACK.

Topic Alias is a separate PUBLISH property, starting at 1 and never exceeding the peer's limit. A real Topic first establishes the mapping; subsequent packets on that connection can omit the repeated Topic name. Mappings do not survive reconnection and are not session state. Setting Topic Alias Max to ten does not automatically create ten mappings.

The V5 feature reduces repeated long-Topic overhead. Independent limits prevent saved bandwidth turning into an unbounded mapping-memory cost. The experiment checks both directions rather than treating one UI number as sufficient evidence.

User Properties are connection metadata, not global message labels

User Properties are repeatable UTF-8 Key/Value pairs. Each uses a two-byte length field; repeated keys are permitted by the protocol. The current Client form supports 100 pairs, while the ordinary connection implementation requires non-empty Key and Value. This count is a product limit, not an MQTT limit.

Add/Remove edits this CONNECT's metadata, such as device-class=sensor or firmware=lab. The application or Broker implementation defines their meaning. CONNECT properties are not automatically forwarded to subscribers or copied onto future PUBLISH packets. Set message metadata separately in the publishing panel.

V5 supplies a standard container for extension metadata without placing everything in a Topic or business payload. It does not define every key or make untrusted metadata an authenticated authorization claim.

CONNECT metadata is separate from PUBLISH metadata; the current form permits 100 pairs.

Last Will: shared basics plus V5 timing and message metadata

A Will is registered with the Broker during CONNECT, not set whenever Publish is pressed. A normal DISCONNECT should not publish it; abnormal connection loss and other triggers follow protocol and Broker behavior.

Topic, Payload, QoS, Retain, and JSON tools

QoS 1 can deliver duplicates. MQTT QoS 2 does not itself guarantee exactly one database write. Retain stores the last retained message for a Topic, not all history, and does not depend on a particular subscriber's session surviving.

Will Delay, Message Expiry, and additional properties

The V5 specification also permits Will Payload Format Indicator and Will User Properties. The current New Client Will area has no independent controls for them. Do not label the publish-panel UTF-8 switch as a Will control, or CONNECT User Properties as Will metadata.

Will Delay must be considered with Session Expiry. If Expiry is zero, the session ends at disconnection, so a ten-second Will Delay alone cannot promise a ten-second notification grace period. The experiment retains the session longer than the delay and separately checks reconnection within that interval and failure to reconnect.

Test Connection, Cancel, and Connect have different outcomes

Test Connection uses the real Client ID. It can take over an existing connection, trigger that connection's Will, or affect sessions and queued messages. A passed test does not verify publish, subscribe, Will permissions, or all quota settings. Broker transport testing and Client authentication testing are different entry points.

Publishing: attach V5 metadata to the specific PUBLISH

Client, Topic, Payload, QoS, and Retain exist in both versions. This is an unsent configuration example.

Client selects the sending connection. Topic is a Topic Name without subscription wildcards. Payload is application content; MQTT does not require JSON. QoS selects 0/1/2, and Retain controls the Topic's retained message. All exist in 3.1.1.

These properties belong to this PUBLISH. Content Type and UTF-8 do not replace business validation.

The reply route and correlation bytes are application conventions. An alias must stay within the peer allowance.

Why not continue putting everything in JSON? V3 applications can implement TTL, request IDs, and content types, but each needs its own payload convention. A Broker generally cannot enforce protocol expiry or routing using an arbitrary business convention. V5 standardizes the metadata container while leaving payload design open.

Message Expiry does not replace application-side timestamp checks. Topic Alias does not guarantee every connection saves bandwidth; inspect whether actual PUBLISH packets established and reused mappings.

Subscriptions: control what comes back and how

V3 has Topic Filter and QoS but no standard MQTT 5 subscription option bits. Alert Monitor is separate.

Change one option at a time when testing. Subscription Identifier reports matching subscriptions, not unique message identity.

Client selects the subscriber. A Topic Filter can use + for one level and # for subsequent levels. QoS requests the highest delivery level; read SUBACK for the grant. The following V5 options are not part of the standard 3.1.1 SUBSCRIBE format.

For RH one, "new" means the Broker's subscription state, not that the user just opened the Client. If a tool unsubscribes before subscribing again, that is not an update to an existing subscription. The experiment directly repeats SUBSCRIBE through an auxiliary client to distinguish RH zero, one, and two.

Shared subscriptions standardize an existing Broker extension

Use $share/group/TopicFilter, for example $share/version-workers/versions/shared. For each matching message, the Broker chooses a subscriber in that group, providing work distribution. It does not promise strict round-robin, even distribution, or exactly-once business processing. The group and filter must satisfy shared-subscription syntax, and No Local must not be set to one for a shared subscription.

The group shares work; it does not promise equal distribution. Some Brokers also support this extension under V3.

MQTT 5 standardizes shared subscriptions, but some Brokers already offer them with 3.1.1. Do not claim V3 systems cannot distribute work; distinguish the standard from Broker extensions. Respect a CONNACK Shared Subscription Available declaration.

Verify with real packets, not configuration alone

The tests use task-owned Mosquitto, EMQX, and the locally fixed Mqttable source Runtime on loopback. Auxiliary protocol clients handle steps the UI cannot precisely control, including delayed PUBACK and repeated SUBSCRIBE. Those results are not attributed to Mqttable button clicks. Packet capture is restricted to this laboratory's ports. The screenshot endpoint 22932 is a loopback recording proxy forwarding to Mosquitto on 22931; readers can connect directly to 22931. That recording proxy is not an MQTT 5 requirement.

A minimal reproducible laboratory

With Mosquitto already installed on macOS or Linux, create a private, separate experiment directory. These commands do not overwrite a configuration. Port 22931 must be free; stop and choose another loopback port if it is occupied.

Anonymous access is for this local experiment, not public deployment. In Mqttable, create Broker mqtt://127.0.0.1:22931, then two distinct Client IDs for 3.1.1 and 5.0. Start with QoS 1 and Retain off, and wait for subscription confirmation before publishing.

Session recovery and message expiry

In this source snapshot, Trace records contain ack_flags, while the inspector reads a different Session Present field name and may not display it. A missing UI row is not zero. Recovery is verified from actual packet flags and the low bit of the Trace record; the CONNACK screenshot below illustrates acceptance and receiving limits only.

These CONNACK limits describe what the Broker receives. Session Present is verified from actual flags, not a missing inspector row.

Actual results and waiting windows appear in the verification table. A screenshot containing no messages does not prove expiry works; negative observations require timing and a successful delivery control.

Reproduce message expiry without writing a client

These commands were tested with this run's Mosquitto 2.1.2. The first subscription creates a session and exits after the expected one-second timeout. Exit code 27 is not an authentication error; stop for other failures. A two-second message TTL followed by a five-second wait means recovery should not deliver stale-command.

Positive control: keep the following subscription running and publish fresh-command from a second terminal. It should arrive. An empty one-second observation by itself is not proof of expiry.

Will delay and request/response

A separate observer subscribes to versions/will/#. The observed client uses a positive Session Expiry longer than Will Delay. A normal Disconnect sends no Will; abnormal loss followed by a wait beyond the delay produces one. Recovering the same session within the delay, with the same Client ID and Clean Start off, suppresses it. With Message Expiry on a retained Will, a later subscriber must not receive that expired state; a fresh publication verifies the path still works.

For request/response, subscribe the requester to versions/reply first. Publish a request with that Response Topic and Correlation Data request-7. The responder subscribes to versions/request, replies to the specified Topic, and returns the same correlation bytes. The Broker does not execute the business operation, and PUBACK is not the business response.

The received PUBLISH carries the correlation bytes and matching subscription ID. PUBACK alone would not prove this reception.

Quotas, aliases, and subscription options

The auxiliary flow-control receiver advertises Receive Maximum two and withholds PUBACK, then acknowledges one message to release budget. The size test advertises 128 bytes, publishes a small message, a 512-byte payload, and another small message. A sender's PUBACK is not proof of subscriber receipt.

The alias test checks both CONNECT and CONNACK budgets, the initial Topic mapping, and subsequent PUBLISH packets. Reconnection requires a new mapping.

Change subscription options individually: No Local compares self-publishing with a different connection; RAP compares the Retain bit on the same live retained publication; RH compares first and repeated subscriptions; Subscription Identifier is checked in received PUBLISH. Shared subscriptions require correct combined message identity and count, not a forced fifty-fifty split.

Results from this run

SCRAM and rejection reasons

The SCRAM-SHA-256 experiment uses a separate EMQX 6.0.0 instance, a scram:built_in_database authenticator, and a synthetic user. Mqttable selects the same method. The tested connection uses a synthetic password stored through Credentials and a SecretRef created through Compact MCP; raw-password form submission is not claimed as accepted. Inspect real AUTH/CONNACK rather than treating a selected dropdown option as authentication success. This does not validate SHA-1, SHA-512, or reauthentication within an existing connection.

Both endpoints must use the same SCRAM method. A configured method is not proof of a successful AUTH exchange.

Read timestamps in chronological order: CONNECT, AUTH challenge, AUTH response, CONNACK. This proves connection authentication, not message permissions.

For rejection, distinguish MQTT 3.1.1 CONNACK return codes from MQTT 5 reason codes; exact values follow the Broker's observed policy. Duplicate Client ID takeover can also produce a server DISCONNECT 0x8E under V5. Reason String is optional: do not fabricate one when the Broker omits it. Use the error-code reference for meanings.

MQTT 5 features that are not New Client input fields

Migrating from 3.1.1 to 5.0

Confirm the Broker and device SDK support V5, then use a non-production identity for a complete message loop. Changing a version string does not preserve every behavioral assumption.

Choosing 3.1.1 does not make a system unreliable. Choosing 5.0 does not automatically repair authentication, reconnection, duplicate processing, or stale business data. Express requirements in configuration, then inspect CONNECT/CONNACK, SUBACK, PUBLISH, and real reception.

Common questions

Does V5 require a different port? No. A listener decides which versions it accepts; a port and MQTT protocol version are different configuration layers.

Are QoS 2, Retain, and JWT new V5 features? No. QoS 2 and Retain exist in V3, and JWT can be ordinary MQTT Password material. V5 adds standard properties, enhanced authentication, and associated behavior.

Can Session Expiry, Message Expiry, Will Delay, and JWT exp replace each other? No. They govern disconnected sessions, message usefulness, Will publication timing, and token validity respectively.

Why is Response Information missing despite Request Response Info? The specification permits the Broker to omit it; response routing and correlation still require application agreement.

Does a restored subscription list prove session recovery? No. A client may have resubscribed. Inspect Session Present and queued delivery to distinguish local configuration from Broker state.

Continue with connection settings, publish and subscribe, Trace, and PCAP analysis. TLS, alerts, and scheduled messages have their own configuration boundaries rather than being MQTT-version differences.