网关子设备

功能概述

设备分类

物联网开发平台根据设备功能性的不同将设备分为如下三类（即节点的分类）：

• 普通设备 ：此类设备可直接接入物联网开发平台且无挂载子设备。
• 网关设备 ：此类设备可直接接入物联网开发平台，并且可接受子设备加入局域网络。
• 子设备 ：此类设备必须依托网关设备才可与物联网开发平台进行通信，例如 Zigbee、蓝牙、RF433 等设备。

操作场景

• 对于不具备直接接入因特网的设备，可先接入本地网关设备的网络，利用网关设备与云端的通信功能，代理子设备接入物联网开发平台。
• 对于在局域网中加入或退出网络的子设备，网关设备可对其在平台进行绑定或解绑操作，并上报与子设备的拓扑关系，实现平台对于整个局域网子设备的管理。

接入方式

• 网关设备接入物联网开发平台的方式与普通设备一致。网关设备接入之后可代理同一局域网下的子设备上/下线，代理子设备上报数据，代理子设备接收云端下发给子设备的数据，并管理与子设备之间的拓扑关系。
• 子设备的接入需通过网关设备来完成，子设备通过网关设备完成身份的认证之后即可成功接入云端。认证方式分为以下两种：
  • 设备级密钥方式 网关获取子设备的设备证书或密钥，并生成子设备绑定签名串。由网关向平台上报子设备绑定签名串信息，代理子设备完成身份的验证。
  • 产品级密钥方式 网关获取子设备的 ProductSecret（产品密钥），并生成签名，由网关向平台发送动态注册请求。验证成功之后平台将返回子设备的 DeviceCert 或 DeviceSecret，网关设备依此生成子设备绑定签名串，并向平台上报子设备绑定签名串信息。验证成功之后即完成子设备的接入。

拓扑关系管理

功能概述

网关类型的设备，可通过与云端的数据通信，对其下的子设备进行绑定与解绑操作。实现此类功能需利用如下两个 Topic：

• 数据上行 Topic（用于发布）：$gateway/up/topo/${productid}/${devicename}
• 数据下行 Topic（用于订阅）：$gateway/down/topo/${productid}/${devicename}

新设备注册

设备上线之前您需要对设备进行身份注册，标识您的设备。 网关绑定子设备请求数据格式：

{
  "method": "register",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subdeviceaaaa"
      }
    ]
  }
}

网关绑定子设备响应数据格式：

{
  "method": "register",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subaaa",
        "deviceSecret": "xxxxxx"
      }
    ]
  }
}

请求参数说明：

字段	类型	描述
method	String	网关消息类型。注册子设备取值为：register
payload.devices	Array	需要注册的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

响应参数说明：

字段	类型	描述
method	String	网关消息类型。绑定子设备取值为：register
payload.devices	Array	要注册的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称
payload.devices.deviceSecret	String	子设备秘钥,拿来绑定设备

绑定设备

网关类型的设备，可以通过数据上行 Topic 请求添加它和子设备之间的拓扑关系，实现绑定子设备。请求成功之后，云端通过数据下行 Topic 返回子设备的绑定结果信息。

网关绑定子设备请求数据格式：

{
  "method": "bind",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subdeviceaaaa",
        "signature": "signature",
        "random": 121213,
        "timestamp": 1589786839,
        "signMethod": "hmacsha256"
      }
    ]
  }
}

网关绑定子设备响应数据格式：

{
  "method": "bind",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subaaa",
        "result": 200
      }
    ]
  }
}

请求参数说明：

字段	类型	描述
method	String	网关消息类型。绑定子设备取值为：bind
payload.devices	Array	需要绑定的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称
payload.devices.signature	String	子设备绑定签名串。 签名算法： 1. 签名原串，将产品 ID 设备名称，随机数，时间戳拼接：text=${product_id};${device_name};${random};${timestamp} 2. 使用设备 Psk 密钥，或者证书的 Sha1 摘要，进行签名：hmac_sha1(device_secret, text),注意:(device_secret 需要先base64 decode) 生产16进制字符串
payload.devices.random	Int	随机数。
payload.devices.timestamp	Int	时间戳，单位：秒。
payload.devices.signMethod	String	签名算法。支持 hmacsha1、hmacsha256。

响应参数说明：

字段	类型	描述
method	String	网关消息类型。绑定子设备取值为：bind
payload.devices	Array	要绑定的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称
payload.devices.result	Int	子设备绑定结果,200表示成功

解绑设备

网关类型的设备， 可以通过数据上行 Topic 请求解绑它和子设备之间的拓扑关系。请求成功之后，云端通过数据下行 Topic 返回子设备的解绑信息。

网关解绑子设备请求数据格式：

{
  "method": "unbind",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subaaa"
      }
    ]
  }
}

网关解绑子设备响应数据格式：

{
  "method": "unbind",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subaaa",
        "result": 200
      }
    ]
  }
}

请求参数说明：

字段	类型	描述
method	String	网关消息类型。解绑子设备取值为：unbind
payload.devices	Array	需要解绑的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

响应参数说明：

字段	类型	描述
method	String	网关消息类型。解绑子设备取值为：unbind
payload.devices	Array	需要解绑的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称
payload.devices.result	Int	子设备绑定结果,200表示成功

云端查询网关可绑定子设备

云端可以通过调用接口查询网关可以配网的子设备列表

下发请求数据格式：

{
  "method": "getFound"
}

请求参数说明：

参数	类型	描述
method	String	网关消息类型。查询子设备取值为：getFound

网关查询子设备拓扑关系响应数据格式：

{
  "method": "getFound",
  "payload": {
    "devices": [
      {
        "productID": "XKFA****LX",
        "deviceName": "2OGDy7Ws8mG****YUe"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "5gcEHg3Yuvm****2p8"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "hmIjq0gEFcf****F5X"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "x9pVpmdRmET****mkM"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "zmHv6o6n4G3****Bgh"
      }
    ]
  }
}

响应参数说明：

参数	类型	描述
method	String	网关消息类型。查询子设备取值为：getFound
payload.devices	Array	网关可以绑定的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

云端通知网关绑定子设备

云端可以通过调用接口通知网关配网子设备列表,无需网关回复

下发请求数据格式：

{
  "method": "notifyBind",
  "payload": {
    "devices": [
      {
        "productID": "XKFA****LX",
        "deviceName": "2OGDy7Ws8mG****YUe"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "5gcEHg3Yuvm****2p8"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "hmIjq0gEFcf****F5X"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "x9pVpmdRmET****mkM"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "zmHv6o6n4G3****Bgh"
      }
    ]
  }
}

请求参数说明：

参数	类型	描述
method	String	网关消息类型。查询子设备取值为：getFound
payload.devices	Array	网关可以绑定的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

网关查询云端拓扑关系

网关类型的设备， 可以通过该 Topic 上行请求查询子设备的拓扑关系。

网关查询子设备拓扑关系请求数据格式：

{
  "method": "getTopo"
}

请求参数说明：

参数	类型	描述
method	String	网关消息类型。查询子设备取值为：getTopo

网关查询子设备拓扑关系响应数据格式：

{
  "method": "getTopo",
  "payload": {
    "devices": [
      {
        "productID": "XKFA****LX",
        "deviceName": "2OGDy7Ws8mG****YUe"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "5gcEHg3Yuvm****2p8"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "hmIjq0gEFcf****F5X"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "x9pVpmdRmET****mkM"
      },
      {
        "productID": "XKFA****LX",
        "deviceName": "zmHv6o6n4G3****Bgh"
      }
    ]
  }
}

响应参数说明：

参数	类型	描述
method	String	网关消息类型。查询子设备取值为：describeSubDevices
payload.devices	Array	网关绑定的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

拓扑关系变化

网关类型的设备， 可以通过该数据下行 Topic 订阅平台对子设备的拓扑关系变化。

子设备被绑定或解绑，网关将收到子设备拓扑关系变化，数据格式如下：

{
  "method": "change",
  "payload": {
    "status": 1,
    "devices": [
      {
        "productID": "CFCS****G7",
        "deviceName": "****ev"
      }
    ]
  }
}

请求参数说明：

参数	类型	描述
method	String	网关消息类型。拓扑关系变化取值为：change
status	Int	拓扑关系变化状态。* 2：解绑* 1：绑定
payload.devices	Array	网关绑定的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

网关响应，数据格式如下：

{
  "method": "change",
  "code":200,
  "msg":"success"
}

响应参数说明：

参数	类型	描述
method	String	网关消息类型。拓扑关系变化取值为：change
code	Integer	200 表示成功
msg	String	当 code 非200的时候，提示错误信息

代理子设备上下线

功能概述

网关类型的设备，可通过与云端的数据通信，代理其下的子设备进行上线与下线操作。此类功能所用到的 Topic 与网关子设备拓扑管理的 Topic 一致：

• 数据上行 Topic（用于发布）：$gateway/up/status/${productid}/${devicename}
• 数据下行 Topic（用于订阅）：$gateway/down/status/${productid}/${devicename}

代理子设备上线

网关类型的设备，可以通过数据上行 Topic 代理子设备上线。请求成功之后，云端通过数据下行 Topic 返回子设备的上线结果信息。
同时联犀会将自动为网关订阅子设备的物模型相关topic和ota相关topic
网关代理子设备上线请求数据格式：

{
  "method": "online",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subdeviceaaaa"
      }
    ]
  }
}

代理子设备上线响应数据格式：

{
  "method": "online",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subdeviceaaaa",
        "result":200
      }
    ]
  }
}

请求参数说明：

字段	类型	描述
method	String	网关消息类型。代理子设备上线取值为：online
payload.devices	Array	需上线的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

响应参数说明：

字段	类型	描述
method	String	网关消息类型。代理子设备上线取值为：online
payload.devices	Array	需上线的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称
payload.devices.result	Int	子设备上线结果，具体错误码 (opens new window) 见下表

代理子设备下线

网关类型的设备， 可以通过数据上行 Topic 代理子设备下线。请求成功之后，云端通过数据下行 Topic 返回成功子设备的下线信息。 同时联犀会将网关订阅该子设备的物模型及ota相关topic删除
网关代理子设备下线请求数据格式：

{
  "method": "offline",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subdeviceaaaa"
      }
    ]
  }
}

网关代理子设备下线响应数据格式：

{
  "method": "offline",
  "payload": {
    "devices": [
      {
        "productID": "CFC******AG7",
        "deviceName": "subdeviceaaaa",
        "result":200
      }
    ]
  }
}

请求参数说明：

字段	类型	描述
method	String	网关消息类型。代理子设备下线取值为：offline
payload.devices	Array	需代理下线的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称

响应参数说明：

字段	类型	描述
method	String	网关消息类型。代理子设备下线取值为：offline
payload.devices	Array	需代理下线的子设备列表
payload.devices.productID	String	子设备产品 ID
payload.devices.deviceName	String	子设备名称
payload.devices.result	Int	子设备下线结果，具体错误码见下表

代理子设备消息

功能概述

网关类型的设备，可通过与云端的数据通信，代理其下的子设备发布和订阅消息。

前提条件

发布和订阅消息之前，请参见 网关设备接入和代理子设备上下线，进行网关设备和子设备接入上线。

发布和订阅消息

网关产品与子产品建立绑定，获取子设备的 Topic 权限后，网关设备可以使用子设备Topic代理进行收发消息，同时可以在设备调试-设备日志中查看通信信息。