在设备对接涂鸦的云端过程中,一部分设备由于自身资源或硬件配置,无法直接连接云端。而是需要通过网关进行中转,由网关代理实现和云端进行数据交互,间接实现设备接入云端。这样的设备也称为子设备。
要想实现网关代理子设备接入云端,子设备和网关需要先建立关联关系,也称为 拓扑关系。
方式对比
建立拓扑关系有三种方式,您可以根据实际情况,选择其中一种,并且注意不要混用。
名称 | 适用场景 | 接口 | 特点 |
---|---|---|---|
动态发现 |
| 网关绑定子设备 | 全自动 |
网关建立拓扑 |
| 建立拓扑关系 | 半自动 |
平台管理 |
| 建立拓扑关系 | 全手动 |
本文主要介绍用于网关设备侧管理拓扑关系的协议内容,并详细说明每个协议。
网关绑定子设备(动态发现)
网关动态发现子设备,请求云端注册子设备并建立拓扑关系,云端返回请求结果。这对应方式对比章节的 动态发现 方式。
交互流程
设备发送消息
设备检测到子设备连接,主动向云端发送绑定子设备消息。
topic: tylink/${deviceId}/device/sub/bind
{"msgId":"45lkj355123****","time":1626197189600,"version":"1.0","data":[{"productId":"a123b456****","clientId":"123455asdf****"},{"productId":"a123b457****","clientId":"453455asdf****"}]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起子设备绑定的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
data | Array | 子设备参数列表 | 是 | 多个子设备绑定参数,子设备数量不超过 100 个。 |
data[].productId | String | 子设备的产品 ID | 是 | 需要绑定在子设备的产品 ID。 |
data[].clientId | String | 设备端唯一 ID | 是 | 此处主要用于子设备硬件的唯一标识,可以是设备的 MAC、SN 等,至少保证产品下唯一,将显示在 设备管理 > 注册 ID 字段。 |
设备接收消息
设备订阅接收绑定子设备消息回复。
topic: tylink/${deviceId}/device/sub/bind_response
{"msgId":"45lkj3551234****","time":1626197189640,"version":"1.0","code":0,"data":[{"productId":"a123b456****","clientId":"123455****","deviceId":"6c828cba434ff40c07****"},{"productId":"a123b457****","clientId":"123456****","deviceId":"6c828cba434ff40c07****"}]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起子设备绑定的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
code | Number | 响应状态码 | 否 |
|
data | Array | 子设备绑定结果列表 | 是 | - |
data[].productId | String | 产品 ID | 是 | 子设备的产品 ID。 |
data[].clientId | String | 子设备硬件的唯一表示 ID | 是 | 子设备的唯一标识,需保证产品下唯一。 |
data[].deviceId | String | 云端分配的唯一设备 ID | 是 | 同一个 clientId 、同一个网关设备 ID,多次绑定只会生成同一个设备 ID,否则会重新生成一个新的设备 ID。 |
状态码说明
状态码 | 说明 |
---|---|
0 | 默认状态,代表成功。 |
1001 | 服务异常。 |
1002 | 请求参数校验不合法。 |
1004 | 设备不存在。 |
2401 | 产品不存在。 |
2402 | 网关绑定了多个设备组。 |
2403 | 拓扑信息存在,子设备信息不存在。 |
2404 | 授权码数量不足, 获取授权码失败。 |
2405 | 获取网关设备组异常。 |
2406 | 子设备重新注册时,必须先解绑。 |
2410 | 同一个网关绑定子设备的数量,不能超过 2000 个。 |
网关删除子设备
网关通过动态发现注册的子设备,可支持网关请求云端删除对应的子设备。云端接收到该请求后,会校验并删除该子设备,同时删除网关和子设备的拓扑关系。由于是设备端发起的删除操作,针对已绑定家庭或资产的子设备,支持网关直接删除子设备。
交互流程
设备发送消息
Topic:tylink/${deviceId}/device/sub/delete
消息内容
{"msgId":"45lkj355123****","time":1626197189600,"version":"1.0","data":["devId123455as****","devId123456ty****"]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起删除子设备的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
data | Array | 待删除的子设备 ID 列表 | 是 | 子设备 ID 列表,设备数量不超过 10。 |
设备接收消息
Topic:tylink/${deviceId}/device/sub/delete_response
消息内容
{"msgId":"45lkj355123****","time":1626197189640,"version":"1.0","code":0,"data":["devId123455as****","devId123456ty****"]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起删除拓扑关系的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
code | Number | 响应状态码 | 否 | 0 代表成功,非 0 代表失败,默认 0 。 |
data | Array | 被删除的子设备 ID 列表。 | 是 | / |
状态码说明
状态码 | 说明 |
---|---|
0 | 默认状态,代表成功。 |
1001 | 服务异常。 |
1004 | 设备记录不存在。 |
2407 | 子设备列表为空。 |
2408 | 子设备数量超限。 |
建立拓扑关系
对于已经在云端注册的子设备,拿到子设备注册信息后烧录到子设备。网关运行后动态发现子设备,请求云端建立拓扑关系,云端返回请求结果。这对应方式对比章节中的 网关建立拓扑 方式。
交互流程
设备发送消息
topic:tylink/${deviceId}/device/topo/add
{"msgId":"45lkj355123****","time":1626197189600,"version":"1.0","data":[{"productId":"a123b456****","deviceId":"123455asdf****","sign":"adstewq35324ds****","signMethod":"HmacSHA256","timestamp":"16067836521"},{"productId":"a123b457****","deviceId":"123456****","sign":"adstewq35324ds****","signMethod":"HmacSHA256","timestamp":"16067836521"}]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起建立拓扑关系的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
data | Array | 子设备参数列表 | 是 | 多个子设备拓扑参数, 子设备数量不能超过 100 个。 |
data[].productId | String | 子设备的产品 ID | 是 | - |
data[].deviceId | String | 子设备的设备 ID | 是 | 注册设备时,获取的设备 ID,云端分配的唯一 ID。 |
data[].signMethod | String | 签名算法 | 是 | 签名算法, 当前仅支持 HmacSHA256。 |
data[].timestamp | String | 时间戳 | 是 | 签名时间戳,10 位秒级或 13 位毫秒级。 |
data[].sign | String | 签名 | 是 | 使用 signMethod 对内容进行签名。例如,HmacSHA256(content, deviceSecret) , content 的内容如:productId= a123b456****|deviceId=123455asdf****|timestamp=${签名时间戳} , deviceSecret 为 涂鸦 IoT 开发平台 设备管理中展示的 DeviceSecret 字段。 |
设备接收消息
topic:tylink/${deviceId}/device/topo/add_response
{"msgId":"45lkj355123****","time":1626197189640,"version":"1.0","code":0,"data":[{"productId":"a123b456****","deviceId":"6c828cba434ff40c07****"},{"productId":"a123b457****","deviceId":"6c828cba434ff40c07****"}]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起建立拓扑关系的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
code | Number | 响应状态码 | 否 |
|
data | Array | 建立拓扑关系成功的结果列表。 | 是 | - |
data[].productId | String | 子设备的产品 ID。 | 是 | - |
data[].deviceId | String | 子设备的设备 ID。 | 是 | - |
状态码说明
状态码 | 说明 |
---|---|
0 | 默认状态,代表成功。 |
1001 | 服务异常。 |
1004 | 设备记录不存在。 |
2407 | 子设备列表为空。 |
2408 | 子设备数量超限。 |
2409 | 签名验证失败。 |
2410 | 同一个网关绑定子设备的数量,不能超过 2000 个。 |
删除拓扑关系
网关请求云端删除与指定子设备的拓扑关系,云端返回请求结果。该请求不会删除子设备。删除拓扑关系后,子设备还能和该网关或其它网关再次建立拓扑关系。
交互流程
设备发送消息
topic:tylink/${deviceId}/device/topo/delete
{"msgId":"45lkj355123****","time":1626197189600,"version":"1.0","data":["devId123455as****","devId123456ty****"]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起删除拓扑关系的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
data | Array | 待删除的子设备 ID 列表 | 是 | 子设备 ID 列表, 设备数量不超过 100 个。 |
设备接收消息
topic:tylink/${deviceId}/device/topo/delete_response
{"msgId":"45lkj355123****","time":1626197189640,"version":"1.0","code":0,"data":["devId123455as****","devId123456ty****"]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起删除拓扑关系的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
code | Number | 响应状态码 | 否 |
|
data | Array | 被删除的子设备 ID 列表 | 是 | - |
状态码说明
状态码 | 说明 |
---|---|
0 | 默认状态,代表成功。 |
1001 | 服务异常。 |
1004 | 设备记录不存在。 |
2407 | 子设备列表为空。 |
2408 | 子设备数量超限。 |
查询拓扑关系
网关请求云端查询拓扑关系,云端返回请求结果。
交互流程
设备发送消息
topic:tylink/${deviceId}/device/topo/get
{"msgId":"45lkj355123****","time":1626197189600,"version":"1.0","data":{"startId": 0,"pageSize": 20, "devIds":["devId123455as****","devId123456ty****"]}
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起查询拓扑关系的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
code | Number | 响应状态码 | 否 |
|
data.startIndexId | Number | 本次查询子设备列表起始值 | 否 | 默认为 0 ,从第一条开始查询。如果查询第二页, 则该值为第一页查询结果最后一条记录的索引 ID。第三页及以后,以此类推。 |
data.pageSize | Number | 每次查询的设备数量 | 否 | 默认及最大查询数量均为 100 个。 |
data.devIds | Array | 本次查询子设备 ID 列表 | 否 | 子设备 ID 列表,设备数量不超过 100 个。 |
设备接收消息
topic:tylink/${deviceId}/device/topo/get_response
{"msgId":"45lkj355123****","time":1626197189640,"version":"1.0","code":0,"data":[{"productId":"a123b456****","deviceId":"6c828cba434ff40c074***","indexId": 1},{"productId":"a123b457****","deviceId":"6c828cba434ff40c074***","indexId": 2}]
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 发起拓扑关系查询的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,上报和订阅消息通过该值建立应答关系。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
code | Number | 响应状态码 | 否 |
|
data | Array | 子设备列表 | 是 | - |
data[].productId | String | 子设备的产品 ID | 是 | - |
data[].deviceId | String | 子设备的设备 ID | 是 | - |
data[].indexId | Number | 索引 ID | 是 | 每页最后一条记录的索引 ID,作为下一页查询的 startIndexId 。 |
状态码说明
状态码 | 说明 |
---|---|
0 | 默认状态,代表成功。 |
1001 | 服务异常。 |
1004 | 设备不存在。 |
2408 | 子设备数量超限。 |
通知拓扑关系变更
云端变更拓扑关系,如往拓扑关系中新增子设备,或把子设备从拓扑关系中删除,发送消息通知网关。
交互流程
设备接收消息
topic:tylink/${deviceId}/device/topo/change
{"msgId":"45lkj355123****","time":1626197189600,"data":{"addDevIds":["devId123asdf****","devId456tyiy****"],"delDevIds":["devId789****","devIdyiy****"]}
}
参数说明
参数 | 类型 | 说明 | 必选 | 备注 |
---|---|---|---|---|
${deviceId} | String | 设备 ID | 是 | 拓扑关系发生变更的网关设备 ID。 |
version | String | 协议版本 | 否 | 默认 1.0,当前仅支持 1.0。 |
msgId | String | 消息 ID | 是 | 总长度不超过 32 位的字符,消息的唯一 ID。 |
time | Number | 消息时间戳 | 是 | 消息发送时的 Unix 时间戳,10 位秒级或 13 位毫秒级。 |
data | object | 业务数据 | 是 | - |
data.addDevIds | Array | 新增的子设备 ID 列表 | 否 | 子设备数量不超过 100 个。 |
data.delDevIds | Array | 删除的子设备 ID 列表 | 否 | 子设备数量不超过 100 个。 |