This topic describes the subscription options in Message Queuing Telemetry Transport (MQTT) 5.0 supported by IoT Platform.
Feature description
You can configure subscription options to determine the actions of IoT Platform. MQTT 5.0 supports the following subscription options:
Item | Description |
This option specifies the Quality of Service (QoS) level for MQTT messaging. The QoS levels in MQTT 5.0 are the same as those in MQTT 3.1. | |
This option specifies whether a device receives messages that are published by itself. | |
This option specifies whether IoT Platform keeps the Retain flag in a message when IoT Platform publishes the message to a device. | |
This option specifies whether the server sends retained messages to devices when the subscription is established. |
If you use Link SDK for C to connect devices and IoT Platform, all subscription options are set to 0 by default.
We recommend that you set the No Local option to 1 to reduce unnecessary message delivery.
QoS level
The following table describes the three QoS levels.
Level | Description | Scenario |
QoS 0 | A message can be received once at most. The message delivery is not reliable and the message may be lost. | This QoS level is used to transmit sensor data. |
QoS 1 | A message can be received at least once. The message delivery is reliable. | This QoS level is used to transmit remote control commands. |
QoS 2 | A message can be received only once. Note IoT Platform does not support this QoS level. | N/A |
No Local
In MQTT 3.1.1, if a device subscribes to a topic to which the device publishes messages, the device can receive messages that are published by itself. However, if MQTT 5.0 is used, you can set the No Local option to 1. This way, when a device subscribes to the topic to which the device publishes messages, the device does not receive messages that are published by itself.
Valid values:
1: The device does not receive messages that are published by itself.
0: The device receives messages that are published by itself.
When a device subscribes to a topic whose name contains wildcard characters, you can set this option to 1. This simplifies subscription and reduces unnecessary messages. The following figure shows the messaging process when the No Local option is set to 1.
Retain As Publish
When IoT Platform forwards a message to a device, you can specify whether to keep the Retain flag in the message.
When you configure a device to subscribe to a topic, you can set the Retain As Publish option to one of the following values:
1: IoT Platform keeps the Retain flag in normal messages that IoT Platform forwards or in retained messages that IoT Platform publishes as the broker.
0: If IoT Platform forwards a normal message, IoT Platform does not keep the Retain flag in the message. If IoT Platform serves as the broker to publish a retained message, IoT Platform keeps the Retain flag in the message.
The following table shows how the Retain As Publish option affects the Retain flag in the message that a device receives from IoT Platform. When a message is published to IoT Platform, the status of the Retain flag in the message can be one of the following values:
True: The message that is published to IoT Platform contains the Retain flag. The Retain As Publish option specifies whether the message that is received by a device contains the Retain flag.
False: The message that is published to IoT Platform does not contain the Retain flag. The Retain As Publish option is invalid, and the message that is received by a device does not contain the Retain flag regardless of the option setting.
Whether the message published to IoT Platform contains the Retain flag | Whether subscription is established when the message is published to IoT Platform | Retain As Publish option | Whether the message received by the device contains the Retain flag |
True | The subscription is established, and IoT Platform immediately publishes the message. | 1 | True |
0 | False | ||
The subscription is not established, and IoT Platform publishes the retained message only after a subscription is established. | 1 | True | |
0 | True | ||
False | The subscription status has no impact. | Any value | False |
If a device receives a message that contains the Retain flag, one of the following conditions is met:
The message that is published to IoT Platform contains the Retain flag and the Retain As Publish option is set to 1.
IoT Platform serves as the broker to publish a retained message and the Retain As Publish flag is set to 0.
Retain Handling
The Retain Handling option specifies whether the server publishes retained messages to devices after a subscription is established.
Valid values:
0: If a device subscribes to a topic, the server publishes retained messages in the topic to the device.
1: If a device never subscribed to a topic and then subscribes to a topic, the server publishes retained messages in the topic to the device. If a device repeatedly establishes subscriptions with the same topic in a session, the device receives retained messages only in the first subscription.
2: The server does not publish retained messages in a topic regardless of whether a device subscribes to the topic.