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

功能概述
对于 BLE、Zigbee、RS485、433 等无法直接访问互联网的设备，可以通过网关接入物联网开发平台。
网关设备负责与物联网开发平台建立连接，并管理局域网中的子设备。子设备通过网关完成身份关联、上下线和消息通信，实现与云端的间接数据交互。腾讯云当前将设备类型划分为普通设备、网关和子设备，其中子设备必须依托网关与物联网开发平台进行通信。
典型架构如下：
﻿
其中，网关承担两个方向的通信
通信方向
说明
北向通信
网关与物联网开发平台进行连接和数据交互。
南向通信
网关通过 BLE、Zigbee、RS485 或其他有线、无线方式连接和管理子设备。
腾讯云现有定义中，网关设备具备北向云端通信和南向子设备管理能力；子设备则通过网关代理与云端交互。
说明：
子设备不直接连接物联网开发平台。子设备与云端之间的消息均由网关进行代理。
设备类型
使用网关与子设备能力前，需要根据设备的联网能力和业务角色选择对应的设备类型。
设备类型
是否直接连接平台
主要作用
普通设备
是
直接连接物联网开发平台并进行消息通信，不挂载子设备。
网关设备
是
连接物联网开发平台，同时管理和代理子设备通信。
子设备
否
通过网关间接连接物联网开发平台。
例如，具备 Wi-Fi 或蜂窝网络能力的家庭网关可以创建为网关设备；通过 BLE 与网关通信的温湿度传感器可以创建为子设备。
网关与子设备的拓扑关系
网关和子设备之间的关联关系称为拓扑关系。
只有当网关与子设备建立拓扑关系后，网关才能代理该子设备完成上下线和消息通信。
拓扑关系包括两个层级。
产品级关联
设备级关联
设备级关联可以预先在控制台完成，也可以由网关在运行过程中动态建立。动态绑定的前提是对应的网关产品和子设备产品已经完成产品级关联。
﻿
接入流程
网关与子设备的整体接入过程如下：
﻿
整个流程可以分为三个阶段：
阶段
主要工作
云端配置
创建网关产品、子设备产品和对应设备，并建立产品之间的关联关系。
设备接入
网关连接物联网开发平台，并建立或获取与子设备之间的拓扑关系。
子设备通信
网关代理子设备上线，并代理子设备与云端进行消息收发。
网关只需要建立一条 MQTT 连接。子设备不单独与物联网开发平台建立 MQTT 连接，而是复用网关已经建立的连接，由网关代理完成上下线和业务消息收发。
前提条件
开始网关与子设备接入前，请确认：
已创建网关产品和子设备产品，详见 创建和删除产品，并建立产品级关联关系。
已创建网关设备和对应子设备，详见 创建设备。
已获取网关设备的 ProductID、DeviceName 及 MQTT 认证信息。
网关已经能够使用自身身份连接物联网开发平台。
已确定设备级拓扑关系的建立方式：提前在平台建立设备级拓扑关系，详见 网关与子设备绑定，或由网关运行时动态绑定子设备。
网关能够通过 BLE、Zigbee、RS485、UART 等本地协议识别并与实际子设备通信。
如果子设备尚未获得平台设备身份，并需要在首次接入时创建设备，请先完成子设备动态注册。
说明：
动态注册用于建立子设备的平台身份；拓扑绑定用于建立子设备与网关之间的管理关系，两者属于不同流程。
子设备不单独建立 MQTT 连接，后续拓扑管理、上下线和业务消息均复用网关已经建立的 MQTT 连接。
网关管理 Topic
网关通过以下 Topic 完成子设备拓扑查询、绑定、解绑和上下线等管理操作：
Topic
方向
QoS
用途
$gateway/operation/{GatewayProductID}/{GatewayDeviceName}
网关 → 平台
0
发送管理请求及应答。
$gateway/operation/result/{GatewayProductID}/{GatewayDeviceName}
平台 → 网关
1
接收操作结果和平台通知。
其中，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)
注意：
网关管理请求使用 QoS 0。
MQTT Publish 成功只表示请求已发送，不表示绑定、上线等业务操作已经完成；最终结果应以操作结果 Topic 返回的 result 为准。
使用注意事项
子设备不会单独建立 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：维护子设备身份并同步拓扑
网关需要维护实际子设备与平台子设备身份之间的映射关系。
实际设备标识
示例
平台侧身份
BLE MAC
AA:BB:CC:DD:EE:FF
SENSOR_PRODUCT / sensor_01
Zigbee 地址
0x1234
SENSOR_PRODUCT / sensor_02
RS485 地址
01
METER_PRODUCT / meter_01
其他私有设备 ID
device-1001
对应 ProductID / DeviceName
网关启动后，可以查询平台当前已经绑定的子设备：
{
  "type": "describe_sub_devices"
}
平台返回：
{
  "type": "describe_sub_devices",
  "payload": {
    "devices": [
      {
        "product_id": "SENSOR_PRODUCT",
        "device_name": "sensor_01"
      }
    ]
  }
}
根据查询结果：
状态
后续处理
子设备已绑定
可进入代理上线流程。
子设备未绑定
提前建立拓扑关系或执行动态绑定。
本地与平台记录不一致
根据业务策略同步本地状态。
步骤 3：动态绑定子设备（可选）
如果需要在网关运行过程中添加新的子设备，可以发送 bind 请求建立设备级拓扑关系。
动态绑定支持设备密钥认证和设备证书认证。
需要准备：
参数
说明
ProductID
子设备所属产品 ID。
DeviceName
子设备名称。
认证信息
DeviceSecret 或证书相关认证信息。
random
随机数。
timestamp
Unix 时间戳，单位为秒。
signature
子设备身份签名。
以设备密钥认证为例，签名原文为：
{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。
根据业务需要，可以选择：
通信方式
适用场景
物模型
属性、事件、行为等标准化设备能力。
自定义 Topic
需要自行定义 Topic 和 Payload 的业务消息。
使用物模型
网关将 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"
    }]
  }
}
其中：
status
含义
1
增加绑定关系。
0
移除绑定关系。
网关更新本地拓扑后，应返回对应处理结果：
{
  "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：代理子设备下线和解绑
当网关检测到实际子设备离线时，应向平台同步子设备状态。
不同南向协议可以根据实际机制判断离线，例如：
南向协议
常见离线判断方式
BLE
连接断开。
Zigbee
离线检测或心跳超时。
RS485
连续通信超时或失败。
发送下线请求：
{
  "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 后，表示设备级拓扑关系解除。
常见问题
现象
排查建议
网关已连接，但子设备无法上线。
检查是否已建立设备级拓扑关系，并确认 online 返回的 result。
动态绑定失败。
检查子设备 ProductID、DeviceName、认证信息、时间戳和签名。
Publish 成功但子设备仍离线。
MQTT Publish 成功不代表上线完成，应等待 online 业务结果。
子设备业务消息无法上报。
检查是否使用子设备自身的业务 Topic，以及 ProductID、DeviceName 是否正确。
云端下发后实际设备未收到。
检查子设备 Topic 订阅、本地身份映射及南向协议转发。
云端解绑后网关仍保留旧设备。
检查是否处理 change 或 unbind_all 并同步本地状态。
网关重启后拓扑状态不确定。
重新发送 describe_sub_devices 查询平台当前绑定关系。

通信方向	说明
北向通信	网关与物联网开发平台进行连接和数据交互。
南向通信	网关通过 BLE、Zigbee、RS485 或其他有线、无线方式连接和管理子设备。

设备类型	是否直接连接平台	主要作用
普通设备	是	直接连接物联网开发平台并进行消息通信，不挂载子设备。
网关设备	是	连接物联网开发平台，同时管理和代理子设备通信。
子设备	否	通过网关间接连接物联网开发平台。

阶段	主要工作
云端配置	创建网关产品、子设备产品和对应设备，并建立产品之间的关联关系。
设备接入	网关连接物联网开发平台，并建立或获取与子设备之间的拓扑关系。
子设备通信	网关代理子设备上线，并代理子设备与云端进行消息收发。

Topic	方向	QoS	用途
`$gateway/operation/{GatewayProductID}/{GatewayDeviceName}`	网关 → 平台	0	发送管理请求及应答。
`$gateway/operation/result/{GatewayProductID}/{GatewayDeviceName}`	平台 → 网关	1	接收操作结果和平台通知。

实际设备标识	示例	平台侧身份
BLE MAC	`AA:BB:CC:DD:EE:FF`	`SENSOR_PRODUCT / sensor_01`
Zigbee 地址	`0x1234`	`SENSOR_PRODUCT / sensor_02`
RS485 地址	`01`	`METER_PRODUCT / meter_01`
其他私有设备 ID	`device-1001`	对应 ProductID / DeviceName

状态	后续处理
子设备已绑定	可进入代理上线流程。
子设备未绑定	提前建立拓扑关系或执行动态绑定。
本地与平台记录不一致	根据业务策略同步本地状态。

参数	说明
`ProductID`	子设备所属产品 ID。
`DeviceName`	子设备名称。
认证信息	DeviceSecret 或证书相关认证信息。
`random`	随机数。
`timestamp`	Unix 时间戳，单位为秒。
`signature`	子设备身份签名。

操作	含义
绑定	建立网关与子设备的管理关系。
上线	表示子设备当前已经通过网关接入平台。

通信方式	适用场景
物模型	属性、事件、行为等标准化设备能力。
自定义 Topic	需要自行定义 Topic 和 Payload 的业务消息。

`status`	含义
`1`	增加绑定关系。
`0`	移除绑定关系。

南向协议	常见离线判断方式
BLE	连接断开。
Zigbee	离线检测或心跳超时。
RS485	连续通信超时或失败。

现象	排查建议
网关已连接，但子设备无法上线。	检查是否已建立设备级拓扑关系，并确认 `online` 返回的 `result`。
动态绑定失败。	检查子设备 ProductID、DeviceName、认证信息、时间戳和签名。
Publish 成功但子设备仍离线。	MQTT Publish 成功不代表上线完成，应等待 `online` 业务结果。
子设备业务消息无法上报。	检查是否使用子设备自身的业务 Topic，以及 ProductID、DeviceName 是否正确。
云端下发后实际设备未收到。	检查子设备 Topic 订阅、本地身份映射及南向协议转发。
云端解绑后网关仍保留旧设备。	检查是否处理 `change` 或 `unbind_all` 并同步本地状态。
网关重启后拓扑状态不确定。	重新发送 `describe_sub_devices` 查询平台当前绑定关系。

网关与子设备

本页目录：

功能概述

设备类型

网关与子设备的拓扑关系

接入流程

前提条件

网关管理 Topic

使用注意事项

接入步骤

步骤 1：网关连接平台

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

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

步骤 4：代理子设备上线

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

使用物模型

使用自定义 Topic

步骤 6：同步云端拓扑变化

拓扑变化

全部解绑

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

常见问题