物联网开发平台 自定义 Topic 通信

一、功能介绍

自定义 Topic 是基于 MQTT 发布/订阅机制提供的自定义消息通道。

自定义 Topic 的前两个层级固定为：

${ProductID}/${DeviceName}

后续层级可以根据业务需要定义，例如：

${ProductID}/${DeviceName}/custom/report${ProductID}/${DeviceName}/custom/control

其中：

自定义 Topic 支持以下设备端操作权限：发布、订阅、发布和订阅。

注意：说明：

二、前提条件

在使用自定义 Topic 进行消息通信前，请确认已完成以下准备：

·已创建产品和设备，详见 创建和删除产品 和 创建设备。

·设备已完成 MQTT 身份认证并成功连接物联网开发平台。

·已配置需要使用的自定义 Topic。

·已根据消息方向配置 Topic 的发布或订阅权限。

注意：说明：

注意：设备实际发布或订阅的 Topic 必须与产品配置的自定义 Topic 保持一致，其中 ${ProductID} 和 ${DeviceName} 应替换为当前设备实际的产品 ID 和设备名称。

三、注意事项

·设备实际使用的 Topic 必须与产品配置的自定义 Topic 保持一致。

·Topic 中的 ProductID 和 DeviceName 应与当前连接设备的身份一致。

·Topic 的发布、订阅权限应与实际消息方向一致。

·自定义 Topic 的 Payload 格式和业务语义由设备端与业务系统自行定义。

·自定义 Topic 与透传 Topic 是不同的通信能力；自定义 Topic 不触发云端解析。

四、步骤 1：准备自定义 Topic

本示例分别使用一个 Topic 进行设备数据上报和消息下发：

注意：Topic 权限从设备端视角定义。“发布”表示设备向平台发送消息；“订阅”表示设备接收平台下发的消息。设备使用无对应权限的 Topic 时，平台会拒绝该操作。

五、步骤 2：订阅下行 Topic

设备连接平台后，需要订阅用于接收业务消息的自定义 Topic。

以下代码以 Python Paho MQTT 为例。示例假设 MQTT Client 已经完成身份认证并成功连接平台。

subscribe_topic = ( f"{product_id}/{device_name}/custom/control")result, mid = client.subscribe( subscribe_topic, qos=1)if result != 0: print(f"订阅请求失败：{result}")else: print(f"正在订阅：{subscribe_topic}")

订阅成功后，设备需要保持 MQTT 消息循环运行，才能持续接收平台发送的消息。

client.loop_forever()

六、步骤 3：接收并处理下行消息

注册 on_message 回调处理已订阅 Topic 的消息：

def on_message(client, userdata, msg): payload = msg.payload.decode("utf-8") print(f"Topic：{msg.topic}") print(f"Payload：{payload}") # 根据业务协议解析 Payload，并执行设备逻辑client.on_message = on_message

例如业务下发：

{ "command": "set_mode", "mode": "eco"}

设备收到后，可以根据自行约定的 Payload 格式解析 command、mode 等字段并执行对应业务逻辑。

注意：说明：

注意：自定义 Topic 不规定 Payload 的字段结构和业务语义。设备端与业务系统需要自行约定消息格式，并确保双方实现一致。

七、步骤 4：发布上行消息

设备需要上报业务数据时，向具有发布权限的自定义 Topic 发布消息。

例如上报温度和湿度：

import jsonpublish_topic = ( f"{product_id}/{device_name}/custom/report")payload = { "temperature": 26.5, "humidity": 60}info = client.publish( publish_topic, payload=json.dumps(payload), qos=1)if info.rc != 0: print(f"消息发布失败：{info.rc}")

如果需要等待 QoS 1 消息发送完成，可以调用：

info.wait_for_publish()

自定义 Topic 的 Payload 可以根据实际业务自行定义，平台不会按照物模型结构解析其中的业务字段。

八、自定义 Topic 与其他 Topic 的区别

九、常见问题