IoT Platform communicates with devices based on topics. Topics are associated with devices, and topic categories are associated with products.

Topic categories

Topic categories are used to simplify authorization and improve topic-based communication between devices and IoT PlatformA topic category indicates a set of topics. For example, a custom topic category named /${YourProductKey}/$ {YourDeviceName}/user/update includes the /${YourProductKey}/device1/user/update and /${YourProductKey}/device2/user/update topics.

Log on to the IoT Platform console. Choose Devices > Products. Find the product, and click View to go to the Product Details page. Click the Topic Categories tab, and then click Topics for Basic Communications, Topics for TSL Communications, or Custom Topics to view topic categories. For more information about the three types of topic categories, see Topic types.

When you use a topic category, take note of the following items:

  • A topic category consists of several fields. Separate these fields with forward slashes (/). A topic category contains the following pre-defined fields: ${YourProductKey} and ${YourDeviceName}. Replace the ${YourProductKey} variable with your ProductKey. Replace the ${YourDeviceName} variable with your DeviceName.
  • Permissions:
    • Publish: Devices can publish messages to the topic.
    • Subscribe: Devices can subscribe to the topic to receive messages.

Topics

Topic categories are used to define topics. Topic categories cannot be used for communication. Only topics can be used for communication.

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

After you create a device under a product, topic categories of the product are automatically mapped to the device to generate topics. You do not need to create topics for the device. Topics are in the same format as topic categories. The difference between topics and topic categories is that the ${YourDeviceName} variable in topic categories is replaced with an actual DeviceName in topics.

Figure 1. Process of generating topics
Topic

The topics of a device can be used for communication only by the device. For example, the /${YourProductKey}/device1/user/update topic belongs to a device named Device 1. Only Device 1 can publish messages and subscribe to this topic. Other devices cannot use this topic.

After the device sends a SUB command to subscribe to a topic, you can perform the following steps to view the subscribed topic. Log on to the IoT Platform console, and choose Devices > Devices. Find the device and click View. On the Device Details page, click the Topic List tab. All subscribed topics are displayed in the Subscribed Topics section. IoT Platform can send upstream messages to these topics.

You can click Post Message next to a topic of a device and send a message to the device by using the topic. The Post Message option is unavailable for topics that include wildcards. For more information, see A topic that includes one or more wildcards.

A device can send a UNSUB request to unsubscribe from a topic. After the topic is unsubscribed, it is removed from the Subscribed Topics section.

If you need to disable message sending and receiving features of a device, 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 control the messages that are sent to the device.

Topic types

Topics are categorized into the following three types.

Parameter Description
Topics for basic communications Topics for basic communications are predefined in IoT Platform. Topics of this type include the following topics:
  • OTA update-related topics. For more information about the purpose and data format of each topic, see OTA update.
  • Device tag-related topics. For more information about the purpose and data format of each topic, see Device tags.
  • Clock synchronization-related topics. Clock synchronization is implemented by using the Network Time Protocol (NTP) service. For more information, see Configure the NTP service.
  • Device shadow-related topics. For more information about the purpose and data format of each topic, see Device shadow data stream.
  • Configuration update-related topics. For more information about the purpose and data format of each topic, see Remote configuration.
  • Broadcast topics. You can call the PubBroadcast API operation of IoT Platform to broadcast messages to devices that subscribe to a broadcast topic. This allows you to batch control the devices.
Topics for TSL communications Topics for Thing Specification Language (TSL) communications are predefined in IoT Platform. Topics of this type include the following topics: For more information about the data format of each TSL-based topic, see Device properties, events, and services.
Note You cannot call the Pub API operation of IoT Platform to send messages to a TSL-based topic.

IoT Platform allows you to perform the following operations to control remote devices by using TSL-based topics: 1. Call the SetDeviceProperty or SetDevicesProperty API operation to set the values of device properties. 2. Call the InvokeThingService or InvokeThingsService API operation to invoke device services.

Edit a topic category You can customize Topic categories on the Topic categories page of a product based on your business requirements. For more information, see custom Topic categories.

A topic category is a configuration template that is used to generate topics. Each topic category of a product is used by all devices within the product. If you edit and update a topic category, the change applies to all topics that are generated by the topic category. This may affect messaging between the devices that subscribe to these topics and IoT Platform. We recommend that you complete the configuration of topic categories when you implement devices. We also recommend that you do not modify or adjust the topic categories after these devices are connected to IoT Platform.