If the Thing Specification Language model feature does not meet your business needs, you can use custom topics for communication between devices and the cloud. You can add and manage custom topics for devices at the product level in the IoT Platform console. A product's custom topic categories are automatically mapped to the custom topics of all devices under that product. IoT Platform does not require a specific data format for custom topic communication, so you can define your own format. This topic describes how to create custom topic categories for a product and explains how to use custom topics for communication.
Background information
For more information about IoT Platform topic definitions and communication, see What is a topic? and Use topics for communication.
Scenarios
Send messages from the server-side to a device
The server-side calls the Pub API operation to publish a message to a specific custom topic. A device subscribes to the topic to receive messages from the server-side.
Send messages from a device to the server-side
A device publishes a message to a custom topic. The server-side can receive the message through an AMQP subscription or the data forwarding feature of IoT Platform.
Device-to-device communication
A device publishes a message to a custom topic. You can use the data forwarding or message routing feature of IoT Platform to forward the message to another device's topic.
Add a custom topic category
Log on to the IoT Platform console.
On the Overview page, find the instance that you want to manage and click the instance ID or instance name.
In the navigation pane, choose .
On the Products page, find the product for which you want to create a custom topic category and click View in the Actions column.
On the product page, click .
Configure the parameters and click OK.
Parameter
Description
Device permission
The permission that a device has on the topic. You can set the permission to one of the following values:
Publish: The device can send messages to IoT Platform through this topic.
Subscribe: After the device subscribes to this topic, IoT Platform sends messages to the device when a server-side application sends messages to this topic.
Publish and Subscribe: The device has both publish and subscribe permissions. It can send messages to and receive messages from IoT Platform through this topic.
Topic category
The topic must use slashes (/) to structure the topic into different levels. Each level can contain only letters, digits, and underscores (_). A level cannot be empty.
For cloud gateway products, you can fully customize the topic category. You can use the wildcard characters
+and#, and use${deviceName}to represent the DeviceName.For non-gateway products:
You can use the wildcard characters
+and#only when the device permission is set to Subscribe. This allows devices to subscribe to topics in batches.The first three levels of a custom topic category are fixed as
/${productKey}/${deviceName}/user/. You must complete the rest of the topic category.
NoteFor more information about how to use wildcard characters, see Custom topics with wildcard characters in this topic.
Enable proxy subscription
You can enable proxy subscription if the device permission is set to Subscribe or Publish and Subscribe.
If you enable this feature, IoT Platform queries the topics for which proxy subscription is enabled and helps the device complete the subscription when the device connects to IoT Platform.
Enable compression or decompression
For Enterprise instances, you can enable data compression or decompression for custom topics. For more information about data compression, see Data compression.
Description
Enter a description for the topic category to distinguish it from others.
Manage topic categories
In the topic category list on the Custom Topic tab, find the custom topic category that you want to manage and perform the following operations.
Edit a topic category
Click Edit in the Actions column of the topic category.
In the Define Topic Category dialog box, modify the Description, Device Permission, and Topic Category.
Click OK.
Enable or disable proxy subscription
Find a topic category whose Device Permission is Subscribe or Publish and Subscribe, and click the Enable Proxy Subscription switch 
or 
.
Delete a topic category
After you delete a custom topic category, communication services related to the custom topic become unavailable and your business may be interrupted. Proceed with caution.
Click Delete in the Actions column of the topic category.
Click OK.
Custom topics with wildcard characters
IoT Platform supports the following wildcard characters when you create custom topic categories.
A topic that contains wildcard characters represents a collection of topics. You cannot use a topic that contains a wildcard character to send a specific message, regardless of its publish or subscribe permissions.
For example, on the Topic List page of a device, you cannot use the Publish Message operation on a topic that contains a wildcard character to publish a message.
Wildcard character | Description |
# | The # character can appear only at the end of a topic. It matches the current level and all subsequent levels. For example, consider the custom topic |
+ | This represents all categories at this level. For example, consider the custom topic |
Examples of custom topic communication
Communication between the server-side and a device:
Device-to-device communication:
Store data from custom topic communication
Data from custom topics can be forwarded to hot data storage. You can click Configure above the topic list to navigate to the Hot Data Storage tab on the Data Service > Data Storage page. On this tab, you can configure rules for hot data storage. For more information, see Configure data storage for custom topics.
Related API operations
Topic management
API | Description |
Creates a custom topic category for a product. | |
Modifies a custom topic category for a product. | |
Queries the custom topic categories of a product. | |
Deletes a custom topic category for a product. | |
Adds a topic route table. | |
Queries a topic route table. | |
Queries a reverse topic route table. | |
Deletes a topic route table. |
Topic communication
API | Description |
Subscribes a specified device to a topic. | |
Queries the list of topics to which a device has subscribed. | |
Specifies whether a custom topic supports broadcast messages that are retained. | |
Publishes a message to a specified device through a custom topic. You can also broadcast a message to online devices that are under a specified product and have subscribed to a specified custom topic. | |
Sends messages in batches to multiple devices under a specified product through a custom topic. | |
Publishes a broadcast message to all devices under a specified product or to all devices that have subscribed to a specified topic. | |
Queries the details of upstream and downstream messages for a device. The details include the message content, the time when the message was generated, and the topic that was used to send the message. |
References
IoT Platform requires that messages reported by devices are in the Alink JSON format. If a device message is not in the Alink JSON format, you must use message parsing to parse the data from the custom topic into the Alink JSON format. No specific data format is required for data that is sent to devices through custom topics. For more information about message parsing, see What is message parsing?.
FAQ
What is the standard JSON format for data in custom topic communication?
Does a physical device need to use the same topic as the device defined for the product?
How do I set and modify the operation permissions for a communication topic?
How long is device data retained in IoT Platform if it is not dumped?