IoT Platform:Topics

Topic categories

Topic categories are defined from the aspect of products. Each topic category indicates a set of topics for different devices in the same product. You can define multiple topic categories for a product. A topic category takes effect for all devices in a product.

The following items describe how to use a topic category:

• Define features for a topic category.

  A topic category consists of several fields. Separate the fields with forward slashes (/). Example: /${productKey}/${deviceName}/user/update.

  The ${productKey} and ${deviceName} fields are fixed. The suffix and prefix fields are used to identify messages with different purposes.

  • ${productKey}: the ProductKey of the product.

    You must replace the variable with an actual ProductKey.

  • ${deviceName}: the DeviceName of the device.

    In a topic category, ${deviceName} is a variable that indicates all devices in the product. You do not need to replace the variable with an actual DeviceName.

• Define permissions on a topic category.

  • Publish: The devices of a product can publish messages to the topics of a topic category.

  • Subscribe: The devices of a product can subscribe to the topics of a topic category to receive messages.

  • Publish and Subscribe: Devices can publish messages to and receive messages from the corresponding topics.

Define a topic

${productKey}/${deviceName} in a topic category specifies a unique device. The topic of the device is generated after the two variables are replaced with actual values.

Topics are in the same format as topic categories. The difference between a topic and a topic category is that the ${deviceName} variable in the topic category is replaced with an actual DeviceName in the topic.

The following examples show the topics of thedevice1 and device2 devices in the a19mzPZ*** product:

• /a19mzPZ****/device1/user/update

• /a19mzPZ****/device2/user/update

The features and permissions of a topic category are mapped to specific topics. The following items describe how to use a topic:

• Topics are used for message communication.

  Important

  When you debug upstream and downstream messaging, make sure that specified topics have the required permissions.

• Topics can be used only by specified devices.

  For example, the /a19mzPZ****/device1/user/update topic belongs to a device named Device 1. Only Device 1 can publish messages to or receive messages from the subscribed topic. Other devices cannot use the topic.

• Manage the messaging of a device.

  To view the status of a device, perform the following steps: Log on to the IoT Platform console and disable the device on the Devices page. You can also call the DisableThing operation on the server to disable the device. If you do not want to disable the device, you can manage the messages that are sent to the device.

Generate topics

The following figure shows how topics are generated.

1. Log on to the IoT Platform console and create a product. For more information, see Create a product.

   After you create a product, IoT Platform predefines topic categories for the product, including Topics for Basic Communications, Topics for TSL Communications, and Custom Topics.

   On the Product Details page, click the Topic Categories tab to view topic categories. For more information, see Classify topics. On the Topic Categories tab, click Topic Category. On the Topic Category tab, click Edit Topic Category, configure the parameters, and then click OK to create a custom topic category for the product. For more information, see Use custom topics for communication.

2. Add a device to a product. For more information, see Add a device.

   After a device is added, all topic categories of the product are automatically mapped to the device to generate specific topics. The features and permissions of a topic category are also mapped to specific topics. You do not need to create topics for each device.

   Important

   • Topics are displayed on the Topic List tab of the Device Details page only after you configure the device and connect the device to IoT Platform. You can use one of the following methods to subscribe to a topic on which the device has the Subscribe permission and view the topic on the Topic List tab.

     • Use device simulation: After the device goes online, IoT Platform automatically subscribes to the topics for basic communication and topics for Thing Specification Language (TSL) communication that have the Subscribe permission on the device. You can also subscribe to custom topics by using the Upstream Debug feature of custom topics on the Device Simulation page.

     • Use MQTT.fx to simulate the device and connect the device to IoT Platform: After the device goes online, you can use the Subscribe feature to subscribe to topics.

     • Develop Link SDK to connect the device to IoT Platform, activate the device, and then subscribe to topics. For more information, see Step 3.

     • SubscribeTopic: After you connect a configured or simulated device to IoT Platform and the device goes online as expected, you can call this operation to subscribe to a topic for the device.

   • When you debug upstream and downstream messaging, make sure that specified topics have the required permissions.

     On the Topic Categories tab of the Product Details page, you can view the Allowed Operations parameter of each topic.

3. Configure the device and connect the device to IoT Platform.

   Before a device can communicate with IoT Platform and use multiple features of IoT Platform, the device must subscribe to related topics. You must also specify the logic of publishing messages to the topics that have the Publish permission. For more information about how to configure a device, see the Link SDK documentation.

   • The device can send the SUB command to subscribe to specified topics and obtain messages from IoT Platform. For more information about how to configure a device, see the Link SDK documentation.

     Link SDK for C versions 3.1, 3.2, and 4.x provided by IoT Platform support automatic topic subscription. For more information about supported topics, see Automatic topic subscription.

     Important

     A device can subscribe to a system topic that is predefined in IoT Platform, such as /sys/${productKey}/${deviceName}/thing/service/property/set. A device cannot use the /sys/${productKey}/${deviceName}/# expression to subscribe to the system topics whose names start with /sys/${productKey}/${deviceName}.

   • The device can send a message to IoT Platform by sending the PUB command to a topic that has the Publish permission. For more information about how to configure the device, see the Link SDK documentation.

   Verify the device and connect the device to IoT Platform. For more information, see Verify devices.

   After a device sends a SUB command to subscribe to a topic, perform the following steps to view the topic: Log on to the IoT Platform console, choose Devices > Devices, find the device, and then click View in the Actions column. On the Device Details page, click Topic List. On the tab that appears, all subscribed topics are displayed in the Subscribed Topics section.

   Note

   The device can send the UNSUB command to unsubscribe from specified topics. Then, the topics are removed from the Subscribed Topics section.

Use topics for communication

The following figure shows the communication process after a device is connected to IoT Platform.

Classify topics

Topics are classified into topics for basic communication, topics for TSL communication, and custom topics. The following table describes the types of topics.

Limits

The number of topics in a topic category for a product is the same as the number of devices that are added to the product. For more information, see Limits.