Improved client feedback & negative ACKs - MQTT 5 Essentials, Part 5
Written by Christoph Schäbel
Category: MQTT 5 Essentials MQTT 5 IoT
Published: October 23, 2019
Recently, we explored the top reasons why MQTT users are upgrading to MQTT 5 and took a deeper look into the new session and message expiry features in MQTT 5. Today’s post examines the new ways for MQTT brokers to give feedback to clients that MQTT 5 introduces and how these features can simplify the lives of developers and operations.
Who needs more client feedback?
People have been using MQTT in their IoT projects for many years now. As we’ve mentioned previously, the OASIS committee made sure that feedback from actual protocol users was taken into consideration when they created the new MQTT 5 protocol standard. One of the top complaints from most users was a lack of transparency. The scant supply of return codes and a lack of possibilities to communicate limitations or specific circumstances from broker to client resulted in increased difficulty for debugging, especially in multi-vendor projects.
Whether investigating the reason for client disconnects, researching why messages fail to reach their intended target, or ensuring consistency in MQTT client deployments across multiple teams, MQTT v3 users often need to extend the pure protocol features with technology like the HiveMQ Extension SDK. To make overcoming these challenges easier and standardized, MQTT version 5 purposely introduced the following features.
Specific set of features
Let’s focus on several MQTT 5 features that fall under the category of providing more transparency and allowing centralized system control by virtue of the broker.
Feedback on connection establishment
With MQTT version 5, it is now possible for MQTT brokers to give additional feedback to MQTT clients on connection establishment. A number of different properties can be added to the connection acknowledgement packet that tell the client which features the broker supports or the client is allowed to use. This includes the following MQTT features:
- Retained messages
- Wildcard subscriptions
- Subscription identifiers
- Shared subscriptions
- Topic aliases
- Maximum quality of service level the client can use
In addition to notifying the client about enabled and disabled features, the new properties in the CONNACK packet also allow the server to give the client feedback on the limits that are granted to it by the broker. These limits include:
- Keep alive
- Session expiry interval
- Maximum packet size
- Maximum number of topic aliases the client can send
Beyond supporting all of these limits, HiveMQ allows you to configure a maximum for the limits and to disable MQTT features that are not needed in your use case.
Better reason codes
In MQTT version 3.1 and 3.1.1, the number of available reason codes is limited to 5 unsuccessful reason codes. MQTT 5 provides more than 20 unsuccessful reason codes. Additionally, packets that do not have reason codes in MQTT version 3.1 and 3.1.1 now have the possibility to include reason codes with MQTT 5. These packets are UNSUBACK, PUBACK, PUBREC, PUBREL and PUBCOMP.
New reason strings
More reason codes certainly improve the feedback to the clients in all cases, but reason codes lack specific context. Supplying context is where reason strings come into play. As the name implies, a reason string is a string that includes all the context the developer or operations needs for quickly identifying precisely why something happened. The specification describes the context as “… a human readable string designed for diagnostics …”. While reason strings are very useful for development and diagnosis, they can be turned off in HiveMQ’s configuration if the exposure of these details is not desired.
Server-sent disconnect packets
In MQTT 3.1 and 3.1.1, when a client violates any limit that the broker sets, the broker simply closes the client’s connection without providing any direct information to the client about why the connection closed. MQTT version 5 adds server-sent disconnect packets that allow the server to send a DISCONNECT packet to the client before it closes the connection. The server-sent disconnect packet contains a reason code and a reason string that give the client all the details about why the connection is closed. This information drastically simplifies the process of identifying why a broker closed the connection to a specific client.
Multiple packets and message flows are now able to respond with a negative acknowledgement.
In MQTT version 3, the UNSUBACK packet that was sent to the client does not have a payload. Therefore, a client can never be informed if, or why, an UNSUBSCRIBE is unsuccessful. MQTT v5 changes all this. In MQTT 5, the UNSUBACK contains a reason code that informs the client about the success status of its UNSUBSCRIBE attempt with a number of possible reasons for failure. For example, no subscription existed in the first place or the client is not authorized to unsubscribe.
The acknowledgement packets from the publish flow (PUBACK, PUBREL, PUBREC, PUBCOMP) can now send a negative acknowledgement to the client if the server cannot currently process the message that the client sent. For example, because the client is not authorized to publish to this topic. The packet gives the client all the information needed to make the necessary changes without having to contact operations or support to know what went wrong.
Summary and additional information
- MQTT brokers such as HiveMQ let you set a server side max value configuration for the mentioned limits. This is extremely useful in multi-vendor projects in which the operator of the broker may not have control over the settings of the MQTT clients.
- The improved feedback for client significantly simplifies diagnosis for development and operations.
- The added transparency also improves the interoperability between different MQTT clients and brokers.
Learn more about MQTT 5
Over the next few weeks, we will continue our technical deep dive into all of the MQTT 5 features. If you would like to join us, sign up for our newsletter to get regular updates and ensure that you don’t miss a post.