Message Queuing Telemetry Transport (MQTT) is an asynchronous communication protocol based on the TCP/IP protocol stack. MQTT is a lightweight protocol that is used for message transmission in the publish/subscribe mode. MQTT is scalable in unreliable network environments. It is applicable in scenarios where the storage space of device hardware or network bandwidth is limited. The sender and receiver of a message that is transmitted over MQTT are not restricted by time or space. You can connect a device to IoT Platform by using the MQTT protocol.

Supported versions

IoT Platform supports device connection over MQTT. Valid MQTT versions include 5.0, 3.1.1, and 3.1. For more information, see MQTT 5.0, MQTT 3.1.1, and MQTT 3.1.

Note To use the MQTT 5.0 protocol, you must buy an Enterprise Edition instance, and then submit a ticket to apply for the whitelist permission for the instance.

Differences of IoT Platform-based MQTT from standard MQTT

  • Supports MQTT messages including PUB, SUB, PING, PONG, CONNECT, DISCONNECT, and UNSUB.
  • Supports the clean session flag.
  • Does not support will and retained messages.
  • Supports quality of service (QoS) 0 and QoS 1 messages and does not support QoS 2 messages.
  • Does not support setting the QoS on subscriber clients. Only the QoS that is set by publisher clients is valid.
  • Supports the synchronous RRPC mode based on native MQTT topics. A server can call a device service and obtain a response at the same time.

Supported MQTT 5.0 features

Compared with the previous version, MQTT 5.0 provides a large number of new features to improve the performance and ease of use. For more information, see Appendix C. Summary of new features in MQTT 5.0.

IoT Platform supports the following new features of MQTT 5.0:

  • Set the maximum length of messages on clients and servers to filter messages.
    MqttConnectionOptions connOpts = new MqttConnectionOptions();
  • Set the maximum number of QoS 1 messages per second.
    MqttConnectionOptions connOpts = new MqttConnectionOptions();
  • Use the UserProperty parameter to specify a list of properties. This parameter is used to transmit additional property data. Each property consists of a key and a value.
    Note You can add up to 20 properties. Each key cannot start with an underscore (_). The total length of each key and value cannot exceed 128 characters.
    MqttProperties properties = new MqttProperties();
    List<UserProperty> userPropertys = new ArrayList<>();
    userPropertys.add(new UserProperty("key1","value1"));

    After a device is connected to IoT Platform by using the MQTT 5.0 protocol, you can view the submitted UserProperty parameter in IoT Platform logs.

  • Add the ResponseTopic and CorrelationData parameters to achieve communication in a mode that is similar to HTTP-based request/response.

    For example, the requester is a device, and the responder is your business server. After you use the AMQP subscription or data forwarding feature, you can parse the ResponseTopic and CorrelationData parameters from the property data in the message. Then, you can call the Pub operation to send a response to the device.

    MqttProperties properties = new MqttProperties();
    properties.setResponseTopic("/" + productKey + "/" + deviceName + "/user/get");
    • The parsed CorrelationData parameter must be Base64 decoded to the byte array that is submitted by the device.
    • The ResponseTopic or CorrelationData parameter cannot exceed 128 characters in length.
  • Add response codes that devices can use to identify request status and problems.

    For more information, see Troubleshooting.

  • Scale down message communication topics to integers to reduce the size of MQTT messages. This saves bandwidth resources.

Security levels

  • TLS-based TCP connection: high security
    • TLS 1.0, 1.1, and 1.2 are supported. We recommend that you use TLS 1.2 for encryption. TLS 1.0 and 1.1 are previous versions and may pose security risks.
    • Link SDK is configured with TLS 1.2. You do not need to configure the TSL protocol if you use Link SDK.
  • Unencrypted TCP connection: low security
  • IoT Internet Device ID-based TCP connection (IoT Internet Device ID is a chip-level encryption service): high security

Topic specifications

For more information about the definitions and types of topics, see What is a topic?.

You can view system topics on the Device Details page of the IoT Platform console. For information about feature-specific topics, see the documentation about specific features.