MQTT Usage Guide

Overview

Message Queuing Telemetry Transport (MQTT) is a publish/subscribe messaging protocol that transports messages between clients and a server. It is suitable for remote sensors and control devices (such as smart street lamps) that have limited computing capabilities and work in low-bandwidth, unreliable networks through persistent connections. To learn more about the MQTT syntax and interfaces, click here.

MQTTS is a variant of MQTT that uses TLS encryption. MQTTS devices communicate with the platform using encrypted data transmission.

Click to enlarge

Service Flow

MQTT devices communicate with the platform without data encryption. For security purposes, MQTTS access is recommended.

You are advised to use the IoT Device SDK to connect devices to the platform over MQTTS.

Click to enlarge

Create a product on the IoTDA console or by calling the API Creating a Product.
Register a device on the IoTDA console or calling the API Creating a Device.
The registered device can report messages and properties, receive commands, properties, and messages, perform OTA upgrades, and report data using custom topics. For details about preset topics of the platform, see Topic Definition.

You can use MQTT.fx to debug access using the native MQTT protocol. For details, see Developing an MQTT-based Smart Street Light Online.

Constraints

Description	Limit
Number of concurrent connections to a directly connected MQTT device	1
Connection setup requests of an account per second on the device side	Basic edition: 100 Standard edition: See Specifications.
Number of upstream requests for an instance per second on the device side (when average message payload is 512 bytes)	Basic edition: 500 Standard edition: See Specifications.
Number of upstream messages for an MQTT connection	50 per second
Bandwidth of an MQTT connection (upstream messages)	1 MB (default)
Length of a publish message sent over an MQTT connection (Oversized messages will be rejected.)	1 MB
Standard MQTT protocol	MQTT v5.0, MQTT v3.1.1, and MQTT v3.1
Differences from the standard MQTT protocol	Not supported: QoS 2 Not supported: will and retain msg
Security levels supported by MQTT	TCP channel and TLS protocols (TLS v1, TLS v1.1, TLS v1.2, and TLS v1.3)
Recommended heartbeat interval for MQTT connections	Range: 30s to 1200s; recommended: 120s
MQTT message publish and subscription	A device can only publish and subscribe to messages of its own topics.
Number of subscriptions for an MQTT connection	100
Length of a custom MQTT topic	128 bytes
Number of custom MQTT topics added to a product	10
Number of CA certificates uploaded for an account on the device side	100

Communication Between MQTT Devices and the Platform

The platform communicates with MQTT devices through topics, and they exchange messages, properties, and commands using preset topics. You can also create custom topics for connected devices to meet specific requirements.

Data Type	Message Type	Description
Upstream data	Reporting device properties	Devices report property data in the format defined in the product model.
	Reporting device messages	If a device cannot report data in the format defined in the product model, the device can report data to the platform using the device message reporting API. The platform forwards the messages reported by devices to an application or other Huawei Cloud services for storage and processing.
	Batch reporting device properties	A gateway reports property data of multiple devices to the platform.
	Reporting device events	Devices report event data in the format defined in the product model.
Downstream data	Delivering platform messages	The platform delivers data in a custom format to devices.
	Setting device properties	A product model defines the properties that the platform can configure for devices. The platform or application can modify the properties of a specific device.
	Querying device properties	The platform or application can query real-time property data of a specific device.
	Delivering platform commands	The platform or application delivers commands in the format defined in the product model to devices.
	Delivering platform events	The platform or application delivers events in the format defined in the product model to devices.

Preset Topics

The following table lists the preset topics of the platform.

Category	Function	Topic	Publisher	Subscriber
Device message related topics	Device Reporting a Message	$oc/devices/{device_id}/sys/messages/up	Device	Platform
Device message related topics	Platform Delivering a Message	$oc/devices/{device_id}/sys/messages/down	Platform	Device
Device command related topics	Platform Delivering a Command	$oc/devices/{device_id}/sys/commands/request_id={request_id}	Platform	Device
Device command related topics	Device Returning a Command Response	$oc/devices/{device_id}/sys/commands/response/request_id={request_id}	Device	Platform
Device property related topics	Device Reporting Properties	$oc/devices/{device_id}/sys/properties/report	Device	Platform
	Reporting Property Data by a Gateway	$oc/devices/{device_id}/sys/gateway/sub_devices/properties/report	Device	Platform
	Setting Device Properties	$oc/devices/{device_id}/sys/properties/set/request_id={request_id}	Platform	Device
	Returning a Response to Property Settings	$oc/devices/{device_id}/sys/properties/set/response/request_id={request_id}	Device	Platform
	Querying Device Properties	$oc/devices/{device_id}/sys/properties/get/request_id={request_id}	Platform	Device
	Device Returning a Response for a Property Query The response does not affect device properties and shadows.	$oc/devices/{device_id}/sys/properties/get/response/request_id={request_id}	Device	Platform
	Obtaining Device Shadow Data from the Platform	$oc/devices/{device_id}/sys/shadow/get/request_id={request_id}	Device	Platform
	Returning a Response to a Request for Obtaining Device Shadow Data	$oc/devices/{device_id}/sys/shadow/get/response/request_id={request_id}	Platform	Device
Device event related topics	Reporting a Device Event	$oc/devices/{device_id}/sys/events/up	Device	Platform
Device event related topics	Delivering an Event	$oc/devices/{device_id}/sys/events/down	Platform	Device

You can create custom topics on the console to report personalized data. For details, see Custom Topic Communications.

TLS Support for MQTT

TLS is recommended for secure transmission between devices and the platform. Currently, TLS v1.1, v1.2, v1.3, and GMTLS are supported. TLS v1.3 is recommended. TLS v1.1 will not be supported in the future. GMTLS is supported only by the enterprise edition using Chinese cryptographic algorithms.

When TLS connections are used for the basic edition, standard edition, and enterprise edition that support general cryptographic algorithms, the IoT platform supports the following cipher suites:

TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

When the enterprise edition that supports Chinese cryptographic algorithms uses TLS connections, the IoT platform supports the following cipher suites: