A server and a device communicate with each other in IoT Platform by using topics. Topics are associated with devices, and topic categories are associated with products. A topic category of a product is automatically mapped to all devices under the product to generate device-specific topics for message communication.

Topic categories

Topic categories are used to simplify authorization and improve topic-based communication between devices and IoT Platform. A topic category is a set of topics within the same product. For example, a user-defined topic category named /${YourProductKey}/$ {YourDeviceName}/user/update is a set that contains the following two topics: /${YourProductKey}/device1/user/update and /${YourProductKey}/device2/user/update.

After devices are created, all topic categories of the product automatically apply to the devices. You do not need to create topics for individual devices.

Figure 1. Procedure of generating topics
Topics

Description of a topic category:

  • A topic category uses a forward slash (/) to separate fields at different levels. A topic category contains the following fixed fields: ${YourProductKey} and ${YourDeviceName}. ${YourProductKey} specifies the product key. ${YourDeviceName} specifies the device name.
  • A field name can contain only letters, digits, and underscores (_). A field at each level cannot be left empty.
  • A device can have Publish and Subscribe permissions on a topic. Publish indicates that the device can publish messages to the topic. Subscribe indicates that the device can subscribe to the topic.
  • A topic category is a template that can be used to configure topics. After you edit and update a topic category, data communication of all devices under a product may be affected. We recommend that you check topic categories during the device R&D phase and do not change the topic categories after devices go online.
  • The Subscribe permission is used to define whether all devices under a product can send SUB requests to a topic category. The SUB and UNSUB requests must be initiated by devices. After a device sends a SUB request to subscribe to a topic, the subscription is permanently valid. The subscription is cancelled only when the device sends an UNSUB request to the topic.

    To restrict a single device from sending and receiving messages, you can disable the device or control the messages sent to the device in your business. To disable a device, you can go to the Devices page of the console or call the DisableThing operation on a client.

Topics

A topic category is used for topic definition rather than data communication. Only topics can be used for data communication.

  • Topics use the formats that are defined by topic categories. When you use a topic, replace the ${YourDeviceName} variable in a topic category with a specific device name.
  • A topic for a device is generated based on the mapped topic category and the device name. A topic whose name contains a device name can be used for data communication only by the specified device. For example, the /${YourProductKey}/device1/user/update topic belongs to a device named device1. Only device1 can publish messages and subscribe to this topic. Other devices cannot use this topic.

Topic types

IoT Platform topics are categorized into the following three types.

Type Description
Topics for basic communications Topics for basic communications are predefined in IoT Platform. Topics of this type include the following topics:
  • Firmware update-related topics. For more information about the purpose and data format of each topic, see Firmware 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 achieved 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 topic. You can call the PubBroadcast operation of IoT Platform to broadcast messages to the devices that subscribe to the 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. For more information about the data format of each topic for TSL communications, see Device properties, events, and services.
Note You cannot call the Pub operation of IoT Platform to send messages to a topic for TSL communications.

IoT Platform provides the following operations for you to use TSL to control remote devices: 1. Call the SetDeviceProperty or SetDevicesProperty operation to set values of device properties. 2. Call the InvokeThingService or InvokeThingsService operation to invoke device services.

Custom topics You can customize topics on the Topic Categories tab.

Topic wildcards

IoT Platform supports two types of wildcards.

Wildcard Description
# This wildcard must be specified for the last field in a topic and can match any filed values at the current level and sub-levels.

For example, the /a1aycMA****/device1/user/# topic can match the following topics: /a1aycMA****/device1/user/update and /a1aycMA****/device1/user/update/error.

+ This wildcard can match any field value at the current level.

For example, the /a1aycMA****/device1/user/+/error topic can match the following topics: /a1aycMA****/device1/user/get/error and /a1aycMA****/device1/user/update/error.

Wildcards can be applied in the following two scenarios: