Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Topics
Updated on 2026-09-01 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Topics

When a device connects to IoTDA through MQTT, topics are used in their communication. The following table lists the preset topics in IoTDA.

Category

Topic

Publisher

Subscriber

Function

Device messages

$oc/devices/{device_id}/sys/messages/up

Device

Platform

Device Reporting a Message

$oc/devices/{device_id}/sys/messages/down

Platform

Device

Platform Delivering a Message

Device commands

$oc/devices/{device_id}/sys/commands/request_id={request_id}

Platform

Device

Platform Delivering a Command

$oc/devices/{device_id}/sys/commands/response/request_id={request_id}

Device

Platform

Example Upstream Response

Device properties

$oc/devices/{device_id}/sys/properties/report

Device

Platform

Device Reporting Properties

$oc/devices/{device_id}/sys/gateway/sub_devices/properties/report

Device

Platform

Gateway Reporting Device Properties in Batches

$oc/devices/{device_id}/sys/properties/set/request_id={request_id}

Platform

Device

Platform Setting Device Properties

$oc/devices/{device_id}/sys/properties/set/response/request_id={request_id}

Device

Platform

Example Upstream Response

$oc/devices/{device_id}/sys/properties/get/request_id={request_id}

Platform

Device

Platform Querying Device Properties

$oc/devices/{device_id}/sys/properties/get/response/request_id={request_id}

Device

Platform

Example Upstream Response

$oc/devices/{device_id}/sys/shadow/get/request_id={request_id}

Device

Platform

Device Obtaining Device Shadow Data from the Platform

$oc/devices/{device_id}/sys/shadow/get/response/request_id={request_id}

Platform

Device

Example Downstream Response

Device events

$oc/devices/{device_id}/sys/events/up

Device

Platform

Device event reporting and platform event delivery, which can be used for Gateway and Child Device Management, Software and Firmware Upgrade, File Upload and Download, Device Time Synchronization, Device Reporting Information, Device Log Collection and Remote Configuration

$oc/devices/{device_id}/sys/events/down

Platform

Device
  • {device_id} identifies the target device that messages with a specific topic will be routed to. When a device subscribes to a topic or pushes messages to a topic, the value of this parameter must be replaced with the device ID used for establishing an MQTT connection between the device and the platform.
  • {request_id} is used to uniquely identify a request. If this parameter is carried in a message sent by a device, ensure that the parameter value is unique on the device by using an incremental number or UUID. request_id in the response returned by the device must be the same as that contained in the topic received by the device from IoTDA.
  • When a device subscribes to a topic with the {request_id} parameter, the parameter can be replaced with the number sign (#). For example, when a device subscribes to the command delivery topic $oc/devices/{device_id}/sys/commands/request_id={request_id}, the topic can be specified as $oc/devices/{device_id}/sys/commands/#.
  • IoTDA uses implicit subscription. Devices do not need to subscribe to the downstream system topic. Devices subscribe to the system topic whose QoS is 0 by default. If the downstream system topic whose QoS is 1 is required, devices need to be configured to subscribe to the topic.
  • Except device_id and request_id, other fields are system fields.