MQTT messaging

MQTT is an open standard that is managed by the OASIS standards organization and international recognized by ISO and is the primary protocol that devices and applications use to communicate with the IoT tool.

Note: In 8.10 and later, You can use HTTP messaging for low volume scenarios. Do not use HTTP messaging for message rates that are greater than 1000 messages per second. HTTP messaging requires a TLS handshake and authentication on every message that is published, and the authentication requires a database lookup for the device authentication token. These requirements put a strain on the authentication service and the IoT tool database. MQTT messaging ingest rates are 2 - 3 orders of magnitude faster than HTTP messaging.

MQTT is a publish and subscribe messaging transport protocol that is designed for the efficient exchange of near real-time data between sensor and mobile devices. For more information, see OASIS Message Queuing Telemetry Transport.

MQTT runs over TCP/IP, and while it is possible to code directly to TCP/IP, you can also choose to use a library that handles the details of the MQTT protocol for you. A wide range of MQTT client libraries are available. IBM contributes to the development and support of several client libraries, including the ones that are available at the following sites:

Standards and requirements

For more information about the versions of MQTT that are supported by the IoT tool, see Standards and requirements.

Restrictions and limitations

For more information about the restrictions and limitations that apply to MQTT clients when connected to the IoT tool, see Restrictions and limitations.

Port security

Devices, gateways, and applications connect to the IoT tool by using either the MQTT or HTTP protocol.

Connection type	Protocol	Port number
Secure (TLS)	MQTT and HTTPS	443

MQTT is supported over TCP and WebSockets. MQTT clients connect by using appropriate credentials, such as device authentication tokens for devices and API keys and tokens for applications. The TLS credentials are always encrypted when sent over secure ports.

When you use secure MQTT messaging on port 443, newer client libraries automatically trust the default certificate that is presented by the IoT tool. If this is not the case for your client environment, you can download and use the full certificate chain from messaging.pem. If you upload a custom certificate, you might need to ensure that the appropriate trust chain is added to your client environment.

TLS

You must enable TLS in your application to avoid sending data insecurely.

For more information, see the following topics:

Fair use policy

In 8.10 and later, fair use throttling pauses read operations on connections that exceed the connection limit. The throttling limits for the IoT tool are per device and are based on the device class, for example, device, gateway, or application. These limits are used to prevent Denial-of-Service (DoS) attacks from devices. The throttling limits do not scale with the IoT tool deployment size. Throttling does not apply to short-lived connections that send a few messages, such as connections for HTTP messaging clients. For more information, see Quotas.

To maximize message rates, ensure that your IoT tool data ingest application distributes the load over many MQTT devices or applications. The IoT tool MQTT service is designed to manage many device connections with each device publishing at low rates.

MQTT client authentication

Each MQTT client requires a unique client ID. If you attempt to connect a client in your organization by using a client ID that is already connected, the first connection is disconnected.

Devices and gateways that are connected directly to the IoT tool display a status icon on the dashboard to indicate that they are connected. Devices that are connected indirectly through a gateway are shown as disconnected because the dashboard is unaware of devices that are connected through a gateway.

Messaging quality of service (QoS) levels

The MQTT protocol provides three qualities of service levels for delivering messages between clients and servers. The messaging QoS that is specified when an MQTT message is published directly effects messaging rates. The following table describes the QoS levels:

Table 1. QoS levels
Level	Description
At most once (QoS 0)	The quality of service level 0 (QoS 0) is the fastest mode of transfer. 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. When near real-time data is sent on an interval, use quality of service level 0. If a single message goes missing, it does not really matter because another message that contains newer data is sent shortly afterward. In this scenario, the extra cost of using a higher quality of service does not result in any tangible benefit.
At least once (QoS 1)	With quality of service level 1 (QoS 1), 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. The reliable delivery of the message to the MQTT broker does not mean that Maximo® Monitor will process the message.
Exactly once (QoS 2)	The quality of service level 2 (QoS 2) provides the strongest reliable message delivery but also has the 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. The reliable delivery of the message to the MQTT broker does not mean that Maximo Monitor will process the message. When you are sending commands, if you want confirmation that only the specified command is acted on, and that it will be acted on only once, use the quality of service level 2. In this example, the additional overheads of level 2 can be advantageous over other levels.

Before you use QoS 1 and QoS 2, review the following performance considerations:

Disk I/O performance is critical for QoS 1 and QoS 2 because these levels require disk persistence in the IoT tool messaging components.
The MQTT specification provides a protocol-level flow control negotiation between client and server. The client and server negotiate the number of unacknowledged messages that are allowed on the session. If the client does not have any available message IDs, the client must pause publishing until IDs are available. Message IDs are available when message acknowledgments (ACK) are received. For more information, see the OASIS Standard MQTT specification.

Data ingest rates

To achieve higher data ingest rates, use the MQTT messaging protocol, and keep the device connection open while publishing messages.

The following MQTT messaging pattern keeps the device connection open until all messages are published:

MQTT CONNECT
MQTT PUBLISH
MQTT PUBLISH
MQTT PUBLISH
...

The following MQTT messaging pattern causes device disconnection in between publishing messages. Do not use this type of pattern. Using this type of pattern causes lower data ingest rates.

MQTT CONNECT
MQTT PUBLISH
MQTT DISCONNECT
MQTT CONNECT
MQTT PUBLISH
MQTT DISCONNECT
...

The following factors influence the data ingestion rate:

The messaging protocol. MQTT is a high volume protocol. HTTP is a low volume protocol.
The messaging pattern. To improve data ingestion rate, do not close MQTT sessions after each message is published. Leave the connection open.
The number of devices. To improve data ingestion and message rates, distribute the load over more connections.
The device class. Fair use quotas are based on device class.
The QoS. High levels of messaging reliability require higher costs.