HiveMQ Logo
Client Feedback & Negative ACKs - MQTT 5 Essentials Part 5

Improved Client Feedback & Negative ACKs - MQTT 5 Essentials Part 5

author portrait

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.

At the end of this blog post you will find a video on the same topic.

Who Needs More Client Feedback While Using MQTT?

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.

MQTT 5’s Specific Feature Set

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 in MQTT 5

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 Available in MQTT 5

In MQTT version 3.1 and 3.1.1, the number of available reason codes is limited to 5 unsuccessful reason codes. MQTT v5 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, DISCONNECT and PUBCOMP.

Providing Context with Reason Strings in MQTT 5

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 5

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.

Negative Acknowledgements in MQTT 5

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.

Negative Acknowledgment Example
Exceeding the maxPacketSize is one of the new reason codes for negative acknowledgments.

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. In Part 6 of this series, we will cover User Properties. 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. Do check out MQTT Glossary to know all the key MQTT terminologies.

author Christoph Schaebel

About Christoph Schäbel

Christoph is a software developer for the product HiveMQ. He has been part of HiveMQ's journey from the beginning and is an expert in the practical use of MQTT.
mail icon Contact

newer posts User Properties - MQTT 5 Essentials Part 6
Session and Message Expiry Intervals - MQTT 5 Essentials Part 4 older posts