IoT Platform supports MQTT 5.0 subscription options that let you control message delivery behavior, including QoS levels, local echo suppression, retain flag handling, and retained message delivery.
Feature description
Configure subscription options to control how IoT Platform handles message delivery. MQTT 5.0 supports the following subscription options:
|
Item |
Description |
|
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. |
|
|
Specifies whether a device receives messages published by itself. |
|
|
Specifies whether IoT Platform preserves the Retain flag when forwarding a message to a device. |
|
|
Specifies whether the server sends retained messages to a device when a 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
MQTT 5.0 defines three QoS levels.
|
Level |
Description |
Scenario |
|
QoS 0 |
A message is delivered at most once. Delivery is not guaranteed and the message may be lost. |
Suitable for transmitting sensor data. |
|
QoS 1 |
A message is delivered at least once. Delivery is guaranteed. |
Suitable for transmitting remote control commands. |
|
QoS 2 |
A message is delivered exactly once. Note
IoT Platform does not support this QoS level. |
N/A |
No Local
In MQTT 3.1.1, a device that subscribes to a topic it publishes to receives its own messages. In MQTT 5.0, you can set the No Local option to 1 so that a device does not receive messages it published itself.
Valid values:
-
1: The device does not receive messages it published itself.
-
0: The device receives messages it published itself.
For wildcard topic subscriptions, set this option to 1 to simplify subscriptions and reduce unnecessary messages. The following figure shows the messaging process when No Local is set to 1.
Retain As Publish
When IoT Platform forwards a message to a device, you can specify whether to preserve the Retain flag in the message.
When configuring a device subscription, set the Retain As Publish option to one of the following values:
-
1: IoT Platform preserves the Retain flag in forwarded normal messages and in retained messages that IoT Platform publishes as the broker.
-
0: For forwarded normal messages, IoT Platform removes the Retain flag. For retained messages that IoT Platform publishes as the broker, the Retain flag is preserved.
The following table shows how the Retain As Publish option affects the Retain flag in messages received by a device. The Retain flag status of the message published to IoT Platform can be:
-
True: The published message contains the Retain flag. The Retain As Publish option determines whether the device receives the flag.
-
False: The published message does not contain the Retain flag. The Retain As Publish option has no effect, and the device never receives the Retain flag.
|
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 |
A device receives a message with the Retain flag when one of the following conditions is met:
-
The published message contains the Retain flag and Retain As Publish is set to 1.
-
IoT Platform publishes a retained message as the broker and Retain As Publish is set to 0.
Retain Handling
The Retain Handling option controls whether the server delivers retained messages to a device after a subscription is established.
Valid values:
-
0: The server delivers retained messages to the device whenever it subscribes to a topic.
-
1: The server delivers retained messages only on the first subscription to a topic. If a device resubscribes to the same topic within a session, retained messages are not sent again.
-
2: The server does not deliver retained messages, regardless of the subscription status.