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 Platform Service.
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. 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:
For information about the versions of MQTT that are supported by Platform Service, see Standards and requirements.
For more information about the restrictions and limitations that apply to MQTT clients when connected to Platform Service, see Restrictions and limitations.
orgId.messaging.internetofthings.ibmcloud.com
Notes
Devices, gateways, and applications connect to the Platform Service by using either the MQTT or HTTP protocol. Connections can be nonsecure or secure.
| Connection type | Protocol | Port number |
|---|---|---|
| Nonsecure* | MQTT and HTTP | 1883 or 80 |
| Secure (TLS) | MQTT and HTTPS | 8883 or 443 |
* Ports 1883 and 80 are disabled by default for messaging. For more information about changing the default setting, see Configuring security policies.
Important: If you are running Platform Service as a component of IBM® Maximo® Application Suite, MQTT connections are supported for port 443 only due to route limitations.
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. Because MQTT messaging to the insecure port 1883 sends these credentials in plain text, always use the secure alternatives 8883 or 443 instead. The TLS credentials are always encrypted when sent over secure ports.
When you use secure MQTT messaging on ports 8883 or 443, newer client libraries automatically trust the default certificate that is presented by Platform Service. 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.
Important: You must enable TLS in your application to avoid sending data insecurely.
For more information, see the following topics:
Important: 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 Platform Service 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.
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'.
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.
Tip: When 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.
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.
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.
Tip: 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. This is an example of when the additional overheads of level 2 can be advantageous over other levels.