物联网开发平台 自定义透传协议

一、功能介绍

创建产品时，数据协议默认采用物模型，也可以选择自定义协议进行透传。

自定义透传使用平台规定的上下行透传 Topic：

上行数据发布至 $thing/up/raw/{ProductID}/{DeviceName}，下行数据通过订阅 $thing/down/raw/{ProductID}/{DeviceName} 接收。

自定义透传只定义数据传输方式。Payload 中各字段的含义、长度、编码和业务协议由设备端与业务系统自行约定。

二、与物模型、自定义 Topic 的区别

透传 Topic 用于非 JSON 格式业务数据，自定义 Topic 则允许用户自行定义 Topic 后续层级。

三、通信流程

通信流程参见下图：

四、前提条件

使用自定义透传进行通信前，请确认：

·已创建数据协议为自定义透传的产品和设备。

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

·已确定设备端与业务系统之间使用的数据协议。

·已明确 Payload 的字段、长度、数据类型、编码方式及字节序。

如果尚未完成设备 MQTT 连接，请先参见设备密钥认证或设备证书认证相关文档。

五、使用限制

腾讯云当前 MQTT 接入协议明确不支持 QoS 2 和 Retain Message；产品限制规定单条 MQTT 发布消息最大为16KB。

六、注意事项

·自定义透传使用平台规定的透传 Topic，不应与自定义 Topic 混用。

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

·ProductID 和 DeviceName 必须与当前连接设备身份一致。

·上下行两端应保持字段定义、长度、数据类型和字节序一致。

·二进制协议应显式完成序列化和反序列化，避免直接依赖设备内存结构。

·设备需要保持 MQTT 消息循环运行，才能持续接收下行数据。

·这篇使用的12字节二进制协议仅为示例，不是平台强制协议。

七、步骤 1：定义透传数据格式

自定义透传不限定 Payload 的数据格式。开发者需要根据实际设备能力自行设计通信协议。

以下以一个简单的智能灯二进制协议为例。

八、上行数据格式

对应示例 Payload：AA 55 01 00 00 00 00 00 01 01 38 00

现有示例程序实际发送的上行数据即采用该字节结构，其中 0x01 表示数据上报、0x20 表示控制消息。

注意：说明：

注意：上述协议仅用于说明自定义透传数据的组织方式，不是物联网开发平台规定的 Payload 格式。实际产品可根据自身协议自行定义。

九、步骤 2：订阅下行透传 Topic

设备连接平台后，需要订阅下行透传 Topic：

down_topic = ( f"$thing/down/raw/" f"{product_id}/{device_name}")client.subscribe( down_topic, qos=1,)

其中，ProductID 和 DeviceName 应与当前 MQTT 连接对应的设备身份保持一致。

现有透传示例同样使用 QoS 1 订阅该下行 Topic。

十、步骤 3：接收并解析下行数据

设备通过 MQTT 消息回调接收下行二进制 Payload。

def on_message(client, userdata, msg): payload = msg.payload print(f"Topic：{msg.topic}") print(f"Payload：{payload.hex(' ').upper()}") # 根据自定义协议解析 Payloadclient.on_message = on_message

例如设备收到：AA 55 20 00 CC CC CC CC FF 01 FF FF

其中 0x20 表示控制消息。现有示例实际接收的下行 Payload 也采用该格式。

例如，可以根据这篇示例协议读取相应字段：

msg_type = payload[2]power_switch = payload[8]color = payload[9]brightness = payload[10]if msg_type == 0x20: # 执行设备控制逻辑 pass

实际开发中，应按照设备自身协议约定的字段偏移、长度和编码方式解析 Payload。

十一、步骤 4：发布上行透传数据

设备需要向平台上报数据时，首先按照自定义协议构造 Payload。

例如：

payload = bytes([ 0xAA, 0x55, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x01, 0x38, 0x00,])

然后发布至上行透传 Topic：

up_topic = ( f"$thing/up/raw/" f"{product_id}/{device_name}")client.publish( up_topic, payload=payload, qos=0,)

现有实现也是将二进制 Payload 直接发布至 $thing/up/raw/{ProductID}/{DeviceName}。

这篇示例上行使用 QoS 0、下行订阅使用 QoS 1，这不是自定义透传 Topic 的强制要求。物联网开发平台支持 QoS 0 和 QoS 1，不支持 QoS 2。

十二、步骤 5：业务系统下发透传数据

业务系统需要向设备下发数据时，可以通过物联网开发平台提供的设备透传指令控制能力向设备订阅的 Topic 发送消息。

对于二进制数据，业务系统可以先将原始 Payload 进行 Base64 编码，并在调用 PublishMessage 时设置：

当 PayloadEncoding 设置为 base64 时，平台会将业务系统提交的 Base64 内容转换回二进制数据后发送至设备。

例如设备需要收到：AA 55 20 00 CC CC CC CC FF 01 FF FF，业务系统应首先对该二进制数据进行 Base64 编码，再通过透传指令控制接口进行下发。设备收到消息后，按照 步骤 3 中定义的协议解析 Payload 并执行业务逻辑。

十三、二进制协议设计建议

使用自定义透传时，协议本身由业务定义。建议至少明确以下内容：

十四、常见问题