In the publish/subscribe Message Queuing Telemetry Transport (MQTT) protocol, topics define the channels for message transmission. Devices publish messages to IoT Platform through topics, and IoT Platform sends messages to devices that subscribe to the topics. To facilitate communication for large numbers of devices based on topics and to simplify authorization, IoT Platform defines product topic categories and device topics. This topic describes the principles of the MQTT protocol and the concepts and categories of topics.
How it works
The preceding figure shows three parties: a device, IoT Platform, and an application server. The communication between the device and IoT Platform is based on the MQTT protocol. For more information about the communication process among the device, application server, and IoT Platform, see Use Topics for Communication.
Message Queuing Telemetry Transport (MQTT) is a message transport protocol based on the publish/subscribe model. It features low overhead, high scalability, a simple protocol, and bidirectional communication. It can establish reliable and efficient persistent connections with minimal device and network resources. MQTT is widely used in the Internet of Things (IoT) field. IoT Platform supports MQTT protocol versions 5.0, 3.1.1, and 3.1. For more information about the protocol specifications, see MQTT protocol specifications.
MQTT client and MQTT broker.
MQTT client: In this topic, a client refers to a device connected to IoT Platform. Devices and application servers do not connect directly. Instead, they communicate through a broker.
MQTT broker: In this topic, the MQTT broker refers to Alibaba Cloud IoT Platform. The broker acts as an intermediary for message communication between devices and application servers. It decouples devices from application servers and enables asynchronous communication between them.
Components of an MQTT message
Topic: A string constructed with forward slashes (/) as separators, such as
/${productKey}/${deviceName}/user/update. All devices that subscribe to this topic receive the message.Payload: The specific content of the message.
Transmission process of an MQTT message, using an application server sending a message to a device as an example
The device subscribes to the corresponding topic.
The server sends a message to IoT Platform.
IoT Platform receives the message, identifies the device based on the message's topic, and sends the message to the device.
The application server receives a confirmation from IoT Platform that the message was sent successfully.
Important MQTT parameters. For more information about other parameters, see MQTT protocol specifications.
Quality of Service (QoS):
QoS=0means that IoT Platform pushes the message to the subscriber only once.QoS=1means that after the subscriber receives the message, it must return apubackmessage to the publisher. Otherwise, the message is pushed again. For more information, see Subscription options.Keepalive interval: When a device initiates a connection, it sends a
CONNECTmessage to IoT Platform. IoT Platform responds with aCONNACKmessage and maintains the connection. The device must send at least one message within the keepalive interval. Otherwise, IoT Platform disconnects from the device. For more information, see MQTT keepalive and Examples.Clean Session: The session state between a device and IoT Platform can be temporary or persistent. For more information, see Session expiry.
Limits
For information about the limits on topics, device access, and communication, see Limits.
Topic types
For detailed descriptions of topics, see the Topic categories and communication instructions section at the end of this topic.
Basic communication topics: Topics that devices must use for features in IoT Platform, such as Thing Specification Language (TSL) model communication, over-the-air (OTA) updates, and task management.
Thing Specification Language model topics: A TSL model is an abstraction of a device's actual functions. It describes what the entity is, what it can do, and what information it can provide from three dimensions: properties, services, and events. For example, the on/off state of a smart fan is a property, the on/off operation is a service, and an alarm is an event. For more information about the concepts and use of TSL models, see What is a TSL model?.
Custom topics: If TSL models do not meet your business needs, you can use custom topics. The first three levels of a custom topic path,
/ProductKey/${deviceName}/user, are fixed. For information about how to manage and use custom topics, see Communicate using custom topics.
Concepts of topic categories and device topics
Basic communication topics and TSL model topics are predefined by IoT Platform and start with
/sys,/ota, or/shadow. To communicate using TSL model topics, you must first create a TSL model for the product. For more information, see Add a single TSL model or Add TSL models in batches.You must create your own custom topics. The relationship between a product's custom topic categories and device topics is shown in the following figure:
Each product has a unique
ProductKey. A product can have multiple topic categories. Each topic category is common to all devices under that product.A product topic category is a collection of topics for the same function shared by all devices under the same product. It starts with
/${productKey}/${deviceName}.Features of the topic category
A topic category starts with a forward slash (/) and is divided by forward slashes into a series of categories, such as
/${productKey}/${deviceName}/user/update. In this example,${productKey}and${deviceName}are fixed categories, and the prefix and suffix categories are used to differentiate messages for different features.${productKey}represents the product identifier, ProductKey. In the topic category for a specific product, replace this with the actualProductKeyvalue, such asa19mzP****.${deviceName}represents the device name. In a product topic category,${deviceName}represents all devices under that product and does not need to be replaced with an actual device name.
Operation permissions for a topic category: The permission entity is the device. The Publish permission allows the device to publish messages to device topics under this topic category. The Subscribe permission allows the device to receive data from IoT Platform.
To allow a server to receive device data, set the permission for the topic category to Publish.
To allow a server to send data to a device, set the permission for the topic category to Subscribe.
NoteAfter you define a product topic category, a device must actively subscribe to a topic that has Subscribe permission. The corresponding topic then appears on the Topic List tab of the device details page. For more information about how a device subscribes to a topic, see Communicate using topics.
Device topic: After you add a device, all of the product's custom topic categories are automatically mapped to the device to generate specific device topics. The operation permissions defined for the product topic category are also mapped to the specific device topics. Based on the product topic category, you can replace
${deviceName}with a specific device name, such asdevice1, to obtain the device topic. For example:/a19mzP****/device1/user/update.A device topic belongs to a specific device and is used for message communication. For more information, see Communicate using topics.
Procedure to define a device topic
In the IoT Platform console, create a product. For more information, see Create a product.
After you create the product, IoT Platform predefines topic categories for it. These include Basic communication topics, TSL model communication topics, and Custom topics. On the Product Details page, click the Topic Category List tab to view the features and their topic categories.
Add a device to the product. For more information, see Create a device.
Create a custom topic category for the product. For more information, see Communicate using custom topics.
Topic categories and communication instructions
The device topics that correspond to the product topic categories predefined by IoT Platform are classified into three types: basic communication topics, TSL model communication topics, and custom topics. The following table provides detailed descriptions.
Type | Topic category and data format | Description |
Basic communication topics | Topics for device OTA update messages. These include topics for devices to report OTA module versions, for IoT Platform to push update package information, for devices to report upgrade progress, and for devices to request the latest update package information. | |
Topic for reporting device tags. Devices report information such as manufacturer and device model. | ||
Topics for Network Time Protocol (NTP) service sync requests and responses. This solves the problem where embedded devices have limited resources, do not include an NTP service, and lack precise timestamps on the client. | ||
Device shadow data is transmitted through topics, including topics for publishing device shadows and for devices to receive shadow changes. | ||
Topics for devices to actively request configuration information and for IoT Platform to push configuration information. Developers can remotely update device system parameters, network parameters, and other configuration information online without restarting or interrupting the device. | ||
Broadcast topic. Call the cloud API PubBroadcast to send broadcast messages to all devices that have subscribed to this topic. This lets you control devices in batches. | ||
TSL model communication topics | Topics for various TSL model features. Note In IoT Platform, you cannot call the Pub API to send messages to TSL model communication topics. In the IoT Platform cloud, to remotely control devices using TSL model features, call SetDeviceProperty or SetDevicesProperty to set device property values. Call InvokeThingService or InvokeThingsService to invoke device services. | |
Custom topics | The system provides three default custom topic categories. You can create custom topic categories based on your business needs. A topic category is a topic template configuration. Editing and updating a topic category may affect communication for all devices under the product that use this topic category. We recommend that you design topic categories during the device development phase and do not change them after the devices are published. |
References
After you define a topic, see Communicate using topics for information about the communication methods among devices, IoT Platform, the server-side, and other cloud products. For more communication methods, see Overview of communication methods in IoT Platform.
For introductory videos on device access and TSL model usage, see Device access.
For the procedures to connect devices of different protocols and types to IoT Platform, see Overview of device access. For information about how to download the device-side Link SDK, see Device access Link SDK.
TSL model topic data is automatically written to time series data storage. For information about how to manage TSL model data storage, see Disable or enable TSL model data storage.
To store custom topic data for queries, you must first create a time series data storage rule. For more information, see Configure custom topic data storage.