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

Item	Constraint
Supported MQTT version	MQTT v3.1, v3.1.1, and v5.0 are supported. QoS 2, and will and retained messages are not supported.
Differences from the standard MQTT protocol	QoS 0 and QoS 1 are supported. Custom topics are supported. QoS 2 is not supported. will and retain msg are not supported.
Security level supported by MQTTS	TCP channel + TLS (TLS 1.3 or earlier)
Maximum number of MQTT connection requests allowed for an account per second	No limit
Maximum number of MQTT connections allowed for a device per minute	1
Maximum throughput of an MQTT connection per second, including directly connected devices and gateways	3 KB/s
Maximum length of a message reported by an MQTT device (A message with the length greater than this value is rejected.)	1 MB
Recommended heartbeat interval for MQTT connections	Range: 30s to 1200s; recommended: 120s
Custom topic	Supported
Publish/Subscribe	A device can only publish and subscribe to messages of its own topics.
Maximum number of subscriptions per subscription request	No limit

You are advised to use encrypted channels (port 8883) for secure communications between devices and the platform.

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 1.0, TLS 1.1, TLS 1.2, and TLS 1.3 are supported. TLS 1.0 and TLS 1.1 will soon be deprecated. Therefore, TLS 1.2 and TLS 1.3 are recommended. The platform only supports the following cipher suites for TLS connections: