MQTT Primer

MQTT is the primary protocol that devices and applications use to communicate with IBM Watson IoT Platform. MQTT is a publish and subscribe messaging transport protocol that is designed for the efficient exchange of real-time data between sensor and mobile devices. MQTT support is available over TCP/IP and websockets, in your configuration file specify options.mqtt.transport=tcp or options.mqtt.transport=websockets

Retained Messages

Watson IoT Platform provides limited support for the retained messages feature of MQTT messaging. If the retained message flag is set to true in an MQTT message that is sent from a device, gateway, or application to Watson IoT Platform, the message is handled as an unretained message.

Quality of Service

The MQTT protocol provides three qualities of service for delivering messages between clients and servers: "at most once", "at least once", and "exactly once". While you can send events and commands by using any quality of service level, you must carefully consider what the right service level is for your needs. Quality of service level '2' is not always a better option than level '0'.

At most once (QoS0)

The "at most once" quality of service level (QoS0) is the fastest mode of transfer and is sometimes called "fire and forget". The message is delivered at most once, or it might not be delivered at all. Delivery across the network is not acknowledged, and the message is not stored. The message might be lost if the client is disconnected, or if the server fails.

The MQTT protocol does not require servers to forward publications at quality of service level '0' to a client. If the client is disconnected at the time the server receives the publication, the publication might be discarded, depending on the server implementation.

At least once (QoS1)

With quality of service level 1 (QoS1), the message is always delivered at least once. If a failure occurs before an acknowledgment is received by the sender, a message can be delivered multiple times. The message must be stored locally at the sender until the sender receives confirmation that the message was published by the receiver. The message is stored in case the message must be sent again.

Exactly once (QoS2)

The "exactly once" quality of service level 2 (QoS2) is the safest, but slowest mode of transfer. The message is always delivered exactly once and must also be stored locally at the sender, until the sender receives confirmation that the message was published by the receiver. The message is stored in case the message must be sent again. With quality of service level 2, a more sophisticated handshaking and acknowledgment sequence is used than for level 1 to ensure that messages are not duplicated.

Subscription Buffers and Clean Session

Each subscription from either a device or application is allocated a buffer of 5000 messages. The buffer allows for any application or device to fall behind the live data it is processing, and to also build up a backlog of up to 5000 pending messages for each subscription it has made. When the buffer is full, the oldest messages are discarded when a new message is received.

Use the MQTT clean session option to access the subscription buffer. When clean session is set to false, the subscriber receives messages from the buffer. When clean session is set to true, the buffer is reset.

Message Payload Limitations

IBM Watson IoT Platform supports sending and receiving messages in any format. MQTT is data-agnostic so it's possible to send images, text in any encoding, encrypted data, or raw data in binary format.

The maximum payload size on Watson IoT Platform is 131072 bytes.

MQTT Keep Alive

The MQTT keep alive interval, which is measured in seconds, defines the maximum time that can pass without communication between the client and broker.

The MQTT client must ensure that, in the absence of any other communication with the broker, a PINGREQ packet is sent. The keep alive interval allows both the client and the broker to detect that the network failed, resulting in a broken connection, without needing to wait for the TCP/IP timeout period to be reached.