Message Delivery Usage
Message delivery is a mode in which the platform directly delivers messages to devices. When a device is offline, the platform caches messages to be delivered until the device goes online.
Introduction for Delayed Message Delivery
- An application or the third-party platform calls the API for delivering a message to a device to send a message to IoTDA. Example message:
POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages Content-Type: application/json X-Auth-Token: ******** { "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name": "messageName", "message": "HelloWorld" }
- The platform sends a 201 Created message carrying the message status PENDING to the application.
- The IoT platform pushes the message result to the application through the API for pushing a device message status change notification. If the device is offline, the message status is PENDING.
Topic: $oc/devices/{device_id}/sys/messages/down Data format: { "resource": "device.message.status", "event": "update", "notify_data": { "message_id": "string", "name": "string", "device_id": "string", "status": "PENDING", "timestamp": "string" } }
- The device goes online.
- The device subscribes to the message delivery topic, which is used to receive messages. For details on the subscribed topic, see 6.
- The platform sends the message to the device according to the protocol specifications. The MQTT device can receive messages delivered by the platform only after subscribing to the topic corresponding to the API Platform Delivering a Message. Example message:
Topic: $oc/devices/{device_id}/sys/messages/down Data format: { "object_device_id": "{object_device_id}", "name": "name", "id": "id", "content": "hello" }
- The IoT platform pushes the final result of the message to the application. The message status is DELIVERED. For details about the used APIs, see Push a Device Message Status Change Notification.
Topic: $oc/devices/{device_id}/sys/messages/down Data format: { "resource": "device.message.status", "event": "update", "notify_data": { "message_id": "string", "name": "string", "device_id": "string", "status": "DELIVERED", "timestamp": "string" } }
Introduction for QoS 1
The following uses an MQTT device as an example to describe how to use a system topic whose QoS is 1 to deliver messages to devices.
- The device goes online.
- Subscribe to a topic for the device and set QoS to 1.
Figure 3 Setting QoS to 1 for the subscribed topic
- An application or third-party platform calls the API for delivering a message to a device to send a message to IoTDA. Example message:
POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages Content-Type: application/json X-Auth-Token: ******** { "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364", "name": "messageName", "message": "HelloWorld" }
- The platform sends the message to the device according to the protocol specifications. The MQTT device can receive messages delivered by the platform only after subscribing to the topic corresponding to the API Platform Delivering a Message. Example message:
Topic: $oc/devices/{device_id}/sys/messages/down Data format: { "object_device_id": "{object_device_id}", "name": "name", "id": "id", "content": "hello" }
- After delivering a message to the device, the IoT platform returns a 201 Created message to the application. The message status is DELIVERED. Message delivery is an asynchronous operation. The platform can return the response without waiting for an ACK message from the device.
- If the IoT platform does not receive an ACK response from the device, it resends the message every 2 seconds for three times by default.
- The device goes online again or subscribes to a topic.
- If the device does not return an ACK response for the previous message and the message does not time out, the IoT platform resends the message every 10 seconds for five times by default. This mechanism of resending every 2 seconds is triggered.
- The platform pushes the final message result to the application. The message status is DELIVERED or TIMEOUT. For details about the used APIs, see Push a Device Message Status Change Notification.
Topic: $oc/devices/{device_id}/sys/messages/down Data format: { "resource": "device.message.status", "event": "update", "notify_data": { "message_id": "string", "name": "string", "device_id": "string", "status": "DELIVERED", "timestamp": "string" } }
Message Delivery Status
The following figure shows the MQTT device message execution status and status change mechanism.
Status |
Description |
---|---|
PENDING |
If an MQTT device is offline, the platform caches the message. In this case, the task status is PENDING. |
TIMEOUT |
If the platform does not deliver the message in the pending status after one day, the task status changes to TIMEOUT. |
DELIVERED |
After the platform sends the message to the device, the task status changes to DELIVERED. |
FAILED |
If the platform fails to send a message to the device, the task status changes to FAILED. |
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot