Configure MNS server-side subscriptions

Background information

Alibaba Cloud Simple Message Queue (formerly MNS) (SMQ) is a distributed messaging service. SMQ enables data transfer and notification delivery between distributed application components.

IoT Platform uses the SMQ queue-based messaging model to receive device messages. Queue-based messaging model features and Basic concepts of the queue-based messaging model.

IoT Platform provides server-side subscriptions and data forwarding. Both forward device messages to an SMQ client for consumption. Data forwarding lets you specify device topics and process data before forwarding. Comparison of data forwarding solutions. Configure data forwarding: Add a data source to forward data and Forward data to Message Service (MNS).

Limits

• MNS server-side subscriptions are not supported for Enterprise instances in the China (Beijing), China (Shenzhen), Singapore, Japan (Tokyo), US (Virginia), US (Silicon Valley), or Germany (Frankfurt) regions.

• MNS server-side subscriptions are not supported for MQTT-based instances.

• Only one SMQ queue subscription is allowed per product. Messages exceeding the MNS server-side subscription limit are not forwarded. Queue-related limits: Limits.

• After you create an MNS server-side subscription, SMQ charges a queue resource usage fee even if no messages are forwarded to the queue.

• Each message received by an SMQ queue cannot exceed 64 KB. Oversized messages are discarded.

Billing

• The number of device messages that you can forward to SMQ depends on the available Message Forwarding TPS specification of the device's instance. For public instances, the Message Forwarding TPS is fixed at 5 messages/second and is free of charge. For Enterprise instances, the Message Forwarding TPS specification is billed on a subscription basis. The available amount depends on the purchased Message Forwarding TPS specification for the instance. Billing overview.

• SMQ charges a fee for receiving messages. Billing.

Create a server-side subscription

When you create an MNS server-side subscription for a product and message type in IoT Platform, a message queue is automatically created in the same region in SMQ under your account. An application that uses the SMQ cloud SDK can listen to this message queue to receive subscribed device messages.

1. Log on to the IoT Platform console.

2. On the Overview page, click All environment. On the All environment tab, find the instance that you want to manage and click the instance ID or instance name.

3. In the navigation pane on the left, choose Message Forwarding > Server-side Subscription.

4. On the Server-side Subscription page, on the Subscription List tab, click Create Subscription.

5. In the Create Subscription dialog box, configure the parameters and click OK.

   Parameter	Description
   Product	Select the product whose devices you want to subscribe to.
   Subscription Type	Select MNS.
   Authorization	Click Authorize, and then activate SMQ and grant permissions as prompted. Note If you have already activated SMQ and granted permissions, skip this step.
   Authorize Now	Click Authorize Now and then click Agree to Authorization. The system creates the AliyunIOTAccessingMNSRole role to grant IoT Platform the permissions to access SMQ and forward messages to SMQ. Note If the AliyunIOTAccessingMNSRole role has been created, skip this step.
   Message Type to Push	Select the message types to subscribe to: Important For products and devices under a cloud gateway, only data from Device-reported messages, Device status change notifications, and Device lifecycle changes can be pushed. Message forwarding topics and data formats: Message communication over MQTT, Message forwarding over GB/T 32960, Message forwarding over JT/T 808, and Message forwarding over SL 651. Device-reported messages: Messages from topics for which the Operation Permission is set to Publish in the topic list of all devices under the product. Device-reported messages include custom data and Thing Specification Language (TSL) model data (reported properties, reported events, responses to property settings, and responses to service invocations). The TSL model data pushed to the server-side is processed by IoT Platform. Data format: Data format. For example, a product has three topic categories: /${productKey}/${deviceName}/user/get, which has the subscribe permission. /${productKey}/${deviceName}/user/update, which has the publish permission. /${productKey}/${deviceName}/thing/event/property/post, which has the publish permission. Then, the server-side subscription pushes messages from topic categories with the publish permission, which are /${productKey}/${deviceName}/user/update and /${productKey}/${deviceName}/thing/event/property/post. Device status change notifications: Messages that are sent when the online or offline status of a device under the product changes. Sub-device discovery reports from gateway: The gateway reports information about discovered sub-devices to IoT Platform. This requires support from the application on the gateway. This message type is specific to gateway products. Device topology changes: Messages about the creation and removal of the topology between a sub-device and a gateway. This message type is specific to gateway products. Device lifecycle changes: Messages about device creation, deletion, disabling, and enabling. TSL model historical data reports: Historical data of properties and events reported by the device. OTA update status notifications: Event notifications for successful or failed device updates during update package verification and batch over-the-air (OTA) updates.

   Table 1. Parameter descriptions

   Message type	Topic description	References
   Device-reported messages: Custom topic	A custom topic for which the Operation Permission is Publish. The topic for forwarding messages in a custom data format is the same as the original custom topic.	Use custom topics for communication
   Device-reported messages: TSL model data	Message forwarding topics include the following: Topic for reporting device properties: /${productKey}/${deviceName}/thing/event/property/post. Topic for reporting device events: /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post. Topic for reporting device properties in a batch: /${productKey}/${deviceName}/thing/property/batch/post. Topic for reporting device events in a batch: /${productKey}/${deviceName}/thing/event/batch/post. Topic for returning a response to a command from the cloud: /${productKey}/${deviceName}/thing/downlink/reply/message.	Device properties Device events Batch reporting of device properties Batch reporting of device events Device responses to downstream commands
   	The corresponding topics for raw data reported by the device are as follows: Topic for reporting device properties: /sys/${productKey}/${deviceName}/thing/event/property/post. Topics for reporting device events: /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post, /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:{tsl.event.identifier}/post. Topic for reporting device properties and events in a batch: /sys/${productKey}/${deviceName}/thing/event/property/batch/post. Topic for returning a response to a command from the cloud: /sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}_reply	Report device properties Report device events Report device properties and events in a batch
   Device status change notifications	IoT Platform directly forwards messages about device online/offline status changes. The topic is /as/mqtt/status/${productKey}/${deviceName}.	Device online/offline status
   Sub-device discovery reports from gateway	A topic specific to gateway devices: /${productKey}/${deviceName}/thing/list/found. The gateway reports information about discovered sub-devices to IoT Platform, and the information is then forwarded.	Gateway discovers a sub-device
   Device topology changes	A topic specific to gateway devices: /${productKey}/${deviceName}/thing/topo/lifecycle. This topic is used to forward messages about the creation and removal of the topology between a sub-device and a gateway.	Device topology changes
   	The corresponding topic for raw data reported by the device: /sys/${productKey}/${deviceName}/thing/topo/change.	Notify a gateway of topology changes
   Device lifecycle changes	IoT Platform directly forwards messages about device creation, deletion, disabling, and enabling. The topic is /${productKey}/${deviceName}/thing/lifecycle.	Device lifecycle changes
   TSL model historical data reports	Message forwarding topics include the following: Topic for reporting historical property data: /${productKey}/${deviceName}/thing/event/property/history/post. Topic for reporting historical event data: /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post.	Historical property reports Historical event reports
   	The topic for reporting historical TSL model data: /sys/${productKey}/${deviceName}/thing/event/property/history/post.	Report historical TSL model data
   OTA update status notifications	Message forwarding topics include the following: Topic for reporting OTA update results: /${productKey}/${deviceName}/ota/upgrade. Topic for reporting OTA update progress: /${productKey}/${deviceName}/ota/progress/post.	OTA update status notifications OTA update progress notifications
   	The topic for reporting update progress: /ota/device/progress/${productKey}/${deviceName}.	Report update progress

6. In the confirmation dialog box that appears, click OK.

   An SMQ queue is automatically created in SMQ. The queue name uses the format aliyun-iot-${productKey}, such as aliyun-iot-ws4******.

   Note

   Deleting an MNS server-side subscription in IoT Platform also automatically deletes the corresponding SMQ queue in SMQ.

Develop a consumer client

After configuring an MNS server-side subscription, use the SMQ cloud SDK on your business server to listen to the SMQ queue and receive subscribed device messages. This allows your SMQ cloud application to receive device messages from IoT Platform.

IoT Platform recommends the ConsumerDemo sample for the queue-based messaging model in the SMQ Java SDK to listen to the created SMQ queue, for example, aliyun-iot-ws4******.

Download the latest sample package from Java SDK release notes. ConsumerDemo in the Queue User Guide .

In the ConsumerDemo file, configure the name of the SMQ queue that was automatically created by IoT Platform, for example, aliyun-iot-ws4******.

CloudQueue queue = client.getQueueRef("aliyun-iot-ws4******");

Data format for received messages

After a device connects to IoT Platform and sends messages, the SMQ client receives messages in the following format. Device-side development: Connect a device using a device SDK.

{
    "messageid":" ",
    "messagetype":"upload",
    "topic":"/al12345****/device123/user/update",
    "payload":" ", 
    "timestamp": " "
}

References

• Check available Message Forwarding TPS resources on the instance details page to ensure device messages can be forwarded to SMQ for consumption. View available resources of an instance. If resources are insufficient, upgrade the instance. Upgrade a billable instance.

• Check received message counts in View queue metrics.

• Push message operation logs to Simple Log Service with the Log Management feature. To diagnose message confirmation exceptions, use the MessageId to query message traces. Push logs to Simple Log Service and View logs in Simple Log Service.

• Tutorial on receiving device status change messages by listening to an SMQ queue: Server-side subscription (MNS) example.

• SMQ provides SDKs in multiple languages (Python, C#, PHP) to listen to SMQ queues. SDK download and usage.