A topic is an intermediary message broker in the publish/subscribe model. Devices can send and receive messages by using topics to achieve communication with IoT Platform. IoT Platform provides topic categories and topics to simplify authorization and improve communication with devices. This topic describes how to define, use, and classify topics.

Define topics

Topic categories are defined from the dimension of products. Each topic category indicates a set of topics for different devices under the same product. A topic category takes effect to all devices with the same ProductKey.

The following items describe how to use a topic category:

  • Define the features of topics.

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

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

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

      You must replace the variable with the actual ProductKey.

    • ${deviceName}: the DeviceName of device.

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

  • Define the permissions of topics.
    • Publish: Devices can publish messages to the corresponding topics.
    • Subscribe: Devices can subscribe to the corresponding topics to receive messages.
    • Publish and Subscribe: Device can publish messages to and receive messages from the corresponding topics.

${productKey}/${deviceName} indicates a unique device. The topic of the device is obtained by specifying these two variables in a topic category.

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 shows the topics of thedevice1 and device2 devices under 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.
    Notice 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 subscribe messages from this topic. Other devices cannot use this topic.

  • Control the message sending and receiving of a device.

    You can 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.

Generate topics

The following figure shows how topics are generated.

Topic
  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. You can also add custom topics for the product. For more information, see Classify topics.

  2. Add a device to a product. For more information, see Create a device.
    After a device is added, all topic categories of the product are automatically mapped to the device to generate specific device 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.
    Notice When you debug upstream and downstream messaging, make sure that specified topics have the required permissions.
  3. Develop the device and connect the device to IoT Platform.

    If a device needs to 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 develop the 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 develop the device, see the Link SDK documentation.

      Link SDK for C versions 3.1, 3.2, and 4.x that are provided by IoT Platform support automatic topic subscription. For a list of supported topics, see Automatic topic subscription.

    • 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 develop the device, see the Link SDK documentation.

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

    After the device subscribes to topics, you can view the topics in the IoT Platform console . In the left-side navigation pane, 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.

    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 the device is connected to IoT Platform.

Communication process
Communication mode Description
Send messages from the device to IoT Platform The device sends messages to IoT Platform by using topics that have the Publish permission. For more information, see Devices send data to IoT Platform.

For information about data formats of topics, see Alink protocol.

Forward data from IoT Platform to enterprise servers IoT Platform forwards device messages to enterprise servers. Device messages can be also forwarded to other topics or Alibaba Cloud services. For more information about how to configure the rules engine, see Configure an AMQP server-side subscription and Configure a data forwarding rule.

For more information about how to forward data to enterprise servers, see IoT Platform forwards data to enterprise servers.

For information about data formats of topics, see Data formats.

Perform remote control on the device An enterprise server calls the API operations of IoT Platform to send messages to the device. For more information, see Perform remote control on devices.
Send messages from IoT Platform to the device In the IoT Platform console, you can send commands or messages to the device by using subscribed topics.
  • On the Maintenance > Online Debug page, you can send commands to the device for debugging. For more information, see Feature debugging.
  • In the Subscribed Topics section, find the topic and click Publish Message in the Actions column to publish a message from IoT Platform to the device. The Publish Message option is unavailable for topics that include wildcards. For more information, see A topic that includes one or more wildcards.
Achieve communication between devices

You can connect devices at two ends to IoT Platform and use IoT Platform to process connection and communication requests between the devices. The following topics describe the two methods that can be used to achieve communication between devices:

Classify topics

Topics are categorized into the following three types.

Type Purpose Description
Topics for basic communications OTA updates This topic is used to transmit messages during OTA updates. The messages are transmitted when the device submits OTA module versions, IoT Platform pushes update packages to the device, the device submits update progresses, and the device requests the information about the latest update package.
Device tags This topic is used to submit device tags. You can specify device tags by using some information about the device, such as the manufacturer and device model.
Clock synchronization This topic is used to synchronize the time of the device with IoT Platform by using the Network Time Protocol (NTP). Embedded devices may not provide the NTP service and no accurate timestamps can be obtained.
Device shadow This topic is used to send device shadow data. IoT Platform can publish a device shadow and the device can receive the updated device shadow.
Configuration update This topic is used to send configuration information. The device can request configuration information from IoT Platform and IoT Platform can push configuration information to the device.

Developers can remotely update the system parameters and network parameters of the device without stopping or restarting the device.

Broadcast messages This topic is used to broadcast messages. You can call the PubBroadcast API operation of IoT Platform to broadcast messages to devices that subscribe to the specified topic. This allows you to control multiple devices at the same time.
Topics for TSL communications Property submission These topics are specific to Thing Specification Language (TSL) models.
Note You cannot call the Pub API operation of IoT Platform to send messages to a TSL-based topic.

IoT Platform allows you to control remote devices by using TSL-based topics. You can call the SetDeviceProperty or SetDevicesProperty API operation to set the values of device properties. You can also call the InvokeThingService or InvokeThingsService API operation to invoke device services.

Property setting
Event submission
Service call
Custom topics Custom topic categories By default, IoT Platform provides three custom topic categories. You can customize topic categories based on your business requirements.

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.