物联网开发平台 网关与子设备

一、功能概述

典型架构如下：

其中，网关承担两个方向的通信

腾讯云现有定义中，网关设备具备北向云端通信和南向子设备管理能力；子设备则通过网关代理与云端交互。

注意：说明：

注意：子设备不直接连接物联网开发平台。子设备与云端之间的消息均由网关进行代理。

二、设备类型

使用网关与子设备能力前，需要根据设备的联网能力和业务角色选择对应的设备类型。

例如，具备 Wi-Fi 或蜂窝网络能力的家庭网关可以创建为网关设备；通过 BLE 与网关通信的温湿度传感器可以创建为子设备。

三、网关与子设备的拓扑关系

网关和子设备之间的关联关系称为拓扑关系。

只有当网关与子设备建立拓扑关系后，网关才能代理该子设备完成上下线和消息通信。

拓扑关系包括两个层级。

·产品级关联

·设备级关联

设备级关联可以预先在控制台完成，也可以由网关在运行过程中动态建立。动态绑定的前提是对应的网关产品和子设备产品已经完成产品级关联。

四、接入流程

网关与子设备的整体接入过程如下：

整个流程可以分为三个阶段：

网关只需要建立一条 MQTT 连接。子设备不单独与物联网开发平台建立 MQTT 连接，而是复用网关已经建立的连接，由网关代理完成上下线和业务消息收发。

五、前提条件

开始网关与子设备接入前，请确认：

·已创建网关产品和子设备产品，详见 创建和删除产品，并建立产品级关联关系。

·已创建网关设备和对应子设备，详见 创建设备。

·已获取网关设备的 ProductID、DeviceName 及 MQTT 认证信息。

·网关已经能够使用自身身份连接物联网开发平台。

·已确定设备级拓扑关系的建立方式：提前在平台建立设备级拓扑关系，详见 网关与子设备绑定，或由网关运行时动态绑定子设备。

·网关能够通过 BLE、Zigbee、RS485、UART 等本地协议识别并与实际子设备通信。

如果子设备尚未获得平台设备身份，并需要在首次接入时创建设备，请先完成子设备动态注册。

注意：说明：

六、网关管理 Topic

网关通过以下 Topic 完成子设备拓扑查询、绑定、解绑和上下线等管理操作：

其中，Topic 中的 ProductID 和 DeviceName 均为网关设备自身身份；被管理的子设备身份通过 Payload 中的 product_id 和 device_name 指定。

网关连接成功后，应订阅操作结果 Topic：

gateway_result_topic = ( f"$gateway/operation/result/" f"{gateway_product_id}/{gateway_device_name}")client.subscribe(gateway_result_topic, qos=1)

七、使用注意事项

·子设备不会单独建立 MQTT 连接，业务通信复用网关 MQTT 连接。

·网关管理 Topic 使用网关自身 ProductID 和 DeviceName，子设备身份通过 Payload 指定。

·建立拓扑关系不代表子设备在线，仍需要执行代理上线。

·MQTT 管理请求发送成功不代表业务操作成功，应以结果 Topic 返回的 result 为准。

·BLE、Zigbee、RS485、UART 等南向协议和设备发现逻辑由开发者自行实现。

·子设备业务消息应使用子设备自身的物模型或自定义 Topic，不应使用 $gateway/operation/…。

·网关应及时处理平台拓扑变化以及实际子设备上下线，保持平台状态和本地状态一致。

九、步骤 1：网关连接平台

网关首先使用自身 ProductID、DeviceName 和认证信息建立 MQTT 连接。

连接成功后：

1. 订阅网关操作结果 Topic。

2. 初始化本地子设备信息。

3. 查询或恢复已有拓扑关系。

4. 根据实际子设备状态执行绑定、上线和业务通信。

十、步骤 2：维护子设备身份并同步拓扑

网关需要维护实际子设备与平台子设备身份之间的映射关系。

网关启动后，可以查询平台当前已经绑定的子设备：

{ "type": "describe_sub_devices"}

平台返回：

{ "type": "describe_sub_devices", "payload": { "devices": [ { "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01" } ] }}

根据查询结果：

十一、步骤 3：动态绑定子设备（可选）

如果需要在网关运行过程中添加新的子设备，可以发送 bind 请求建立设备级拓扑关系。

动态绑定支持设备密钥认证和设备证书认证。

需要准备：

以设备密钥认证为例，签名原文为：

{ProductID}{DeviceName};{random};{timestamp}

核心实现：

random_value = random.randint(1, 2147483647)timestamp = int(time.time())sign_text = ( f"{sub_product_id}{sub_device_name};" f"{random_value};{timestamp}")digest_hex = hmac.new( sub_device_secret.encode(), sign_text.encode(), hashlib.sha1,).hexdigest()signature = base64.b64encode( digest_hex.encode()).decode()

绑定请求：

{ "type": "bind", "payload": { "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01", "signature": "******", "random": 12345, "timestamp": 1786610239, "signmethod": "hmacsha1", "authtype": "psk" }] }}

平台返回对应 bind 结果，result = 0 表示绑定成功。

注意：说明：

注意：动态绑定只建立设备级拓扑关系，不代表子设备已经在线。

十二、步骤 4：代理子设备上线

当实际子设备已经接入网关，并且与当前网关存在拓扑关系后，网关发送 online 请求：

{ "type": "online", "payload": { "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01" }] }}

平台返回：

{ "type": "online", "payload": { "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01", "result": 0 }] }}

result = 0 表示代理上线成功。

十三、步骤 5：代理子设备业务通信

子设备上线后，可以复用网关已经建立的 MQTT 连接进行业务通信。

注意：说明：

注意：复用的是网关 MQTT 连接，不是网关管理 Topic。

注意：$gateway/operation/… 只用于子设备管理，业务数据仍使用子设备自身对应的业务 Topic。

根据业务需要，可以选择：

十四、使用物模型

网关将 BLE、Zigbee、RS485 等南向数据解析后，转换成对应子设备的物模型数据，并通过网关 MQTT 连接发送。

云端下发物模型消息时，网关根据目标 ProductID 和 DeviceName 找到实际子设备，再转换成本地协议发送。

十五、使用自定义 Topic

网关也可以使用子设备自身的自定义 Topic 代理消息：

topic = ( f"{sub_product_id}/" f"{sub_device_name}/custom/report")client.publish( topic, payload=payload, qos=1,)

接收下行消息时订阅对应子设备 Topic：

topic = ( f"{sub_product_id}/" f"{sub_device_name}/custom/control")client.subscribe(topic, qos=1)

收到消息后，根据 Topic 中的 ProductID 和 DeviceName 定位实际子设备，并转换成本地协议发送。

十六、步骤 6：同步云端拓扑变化

网关与子设备的拓扑关系也可能通过 App、业务后台等云端操作发生变化。网关需要处理平台主动下发的拓扑通知，并同步本地状态。

十七、拓扑变化

平台下发：

{ "type": "change", "payload": { "status": 1, "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01" }] }}

其中：

网关更新本地拓扑后，应返回对应处理结果：

{ "type": "change", "payload": { "status": 1, "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01", "result": 0 }] }}

十八、全部解绑

平台可能下发：

{ "type": "unbind_all"}

网关应清理本地绑定和相关会话状态，并返回：

{ "type": "unbind_all", "payload": { "result": 0 }}

注意：说明：

注意：对于 bind、online、offline、unbind 等请求，应根据返回消息中的 type、product_id 和 device_name 匹配对应操作，以 result 判断业务结果。

十九、步骤 7：代理子设备下线和解绑

当网关检测到实际子设备离线时，应向平台同步子设备状态。

不同南向协议可以根据实际机制判断离线，例如：

发送下线请求：

{ "type": "offline", "payload": { "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01" }] }}

平台返回对应 offline 结果，result = 0 表示下线成功。

如果同时需要解除该子设备与网关的拓扑关系，再发送：

{ "type": "unbind", "payload": { "devices": [{ "product_id": "SENSOR_PRODUCT", "device_name": "sensor_01" }] }}

unbind 返回 result = 0 后，表示设备级拓扑关系解除。

20、常见问题