子设备身份注册后,需由网关向物联网平台上报网关与子设备的拓扑关系,然后进行子设备上线。

子设备上线过程中,物联网平台会校验子设备的身份和与网关的拓扑关系。所有校验通过,才会建立并绑定子设备逻辑通道至网关物理通道上。子设备与物联网平台的数据上下行通信与直连设备的通信协议一致,协议上不需要露出网关信息。

删除拓扑关系后,子设备不能再通过网关上线。系统将提示拓扑关系不存在,认证不通过等错误。

添加设备拓扑关系

网关类型的设备,可以通过该Topic上行请求添加它和子设备之间的拓扑关系,返回成功添加拓扑关系的子设备。

重要 单次最多可请求添加30个子设备。

数据上行。

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/topo/add
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/topo/add_reply

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554",
      "sign": "xxxxxx",
      "signmethod": "hmacSha1",
      "timestamp": "1524448722000",
      "clientId": "xxxxxx"
    }
  ],
  "method": "thing.topo.add"
}

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

请求参数说明:

参数类型说明
idString消息ID号。需定义为String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
versionString协议版本号,目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ackIntegersys下的扩展功能字段,表示是否返回响应数据。
  • 1:云端返回响应数据。
  • 0:云端不返回响应数据。
重要 该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

paramsList请求入参。
deviceNameString子设备的名称。
productKeyString子设备所属产品的ProductKey。
signString

签名。

加签算法:

  1. 将所有提交给服务器的参数(signsignMethod除外)按照字母顺序排序,然后将参数和值依次拼接(无拼接符号)。
  2. 对加签内容,需通过signMethod指定的加签算法,使用设备的DeviceSecret值,进行签名计算。
签名计算示例:
sign= hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp1524448722000)
signmethodString签名方法,支持hmacSha1、hmacSha256、hmacMd5、Sha256。
timestampString时间戳(单位:毫秒)。
clientIdString设备本地标记,非必填。可以设置为具体的productKey&deviceName。
methodString请求方法,取值thing.topo.add

响应参数说明:

参数类型说明
idString消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果,200代表成功。
dataObject请求成功时返回的子设备信息,具体参数请参见下表data。
表 1. data
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

错误信息:

错误码消息描述
460request parameter error请求参数错误。
6402topo relation cannot add by self设备不能把自己添加为自己的子设备。
401request auth error签名校验授权失败。

删除设备的拓扑关系

网关类型的设备,可以通过该Topic上行请求删除它和子设备之间的拓扑关系,返回成功删除拓扑关系的子设备。

重要 单次最多可请求删除30个子设备。

数据上行。

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/topo/delete
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/topo/delete_reply

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.delete"
}

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

请求参数说明:

参数类型说明
idString消息ID号。需定义为String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
versionString协议版本号,目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ackIntegersys下的扩展功能字段,表示是否返回响应数据。
  • 1:云端返回响应数据。
  • 0:云端不返回响应数据。
重要 该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

paramsList请求参数。
deviceNameString子设备名称。
productKeyString子设备所属产品的ProductKey
methodString请求方法。取值thing.topo.delete

响应参数说明:

参数类型说明
idString消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果,200代表成功。
dataObject请求成功时返回的子设备信息,具体参数请参见下表data。
表 2. data
参数类型说明
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

错误信息:

错误码消息描述
460request parameter error请求参数错误。
6100device not found设备不存在。

获取设备的拓扑关系

数据上行。

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/topo/get
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/topo/get_reply

网关类型的设备,可以通过该Topic获取该设备和子设备的拓扑关系。

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.topo.get"
}

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

请求参数说明:

参数类型说明
idString消息ID号。需定义为String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
versionString协议版本号,目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ackIntegersys下的扩展功能字段,表示是否返回响应数据。
  • 1:云端返回响应数据。
  • 0:云端不返回响应数据。
重要 该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

paramsObject请求参数,可为空。
methodString请求方法,取值thing.topo.get

响应参数说明:

参数类型说明
idString消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果,200代表成功。
dataObject请求成功时的返回结果。
deviceNameString子设备的名称。
productKeyString子设备所属产品的ProductKey。

错误信息:

错误码消息描述
460request parameter error请求参数错误。

发现设备列表上报

数据上行。

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/list/found
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/list/found_reply

在一些场景下,网关可以发现新接入的子设备。发现后,需将新接入子设备的信息上报云端,然后通过数据流转到第三方应用,选择将哪些子设备接入该网关。

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.list.found"
}

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data":{}
}

请求参数说明:

参数类型说明
idString消息ID号。需定义为String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
versionString协议版本号,目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数,其下包含各功能字段。
说明 使用设备端SDK开发时,如果未设置扩展功能,则无此参数,相关功能保持默认配置。
ackIntegersys下的扩展功能字段,表示是否返回响应数据。
  • 1:云端返回响应数据。
  • 0:云端不返回响应数据。
重要 该功能配置说明,请参见物模型使用示例

如果未配置该功能,则无此参数,云端默认返回响应数据。

paramsObject请求参数,可为空。
methodString请求方法,取值thing.list.found
deviceNameString子设备的名称。
productKeyString子设备所属产品的ProductKey。

响应参数说明:

参数类型说明
idString消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果,200代表成功。
dataObject请求成功时的返回结果。

错误信息:

错误码消息描述
460request parameter error请求参数错误。
6250product not found上报的子设备产品不存在。
6280devicename not meet specs上报的子设备的名称不符规范。

通知网关添加设备拓扑关系

数据下行。

  • 请求Topic:/sys/${productKey}/${deviceName}/thing/topo/add/notify
  • 响应Topic:/sys/${productKey}/${deviceName}/thing/topo/add/notify_reply

通知网关设备对子设备发起添加拓扑关系,可以配合发现设备列表上报功能使用。可以通过数据流转获取设备返回的结果,数据流转Topic为/${productKey}/${deviceName}/thing/downlink/reply/message

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.add.notify"
}

Alink响应数据格式:

{
  "id": "123",
  "code": 200,
  "data": {}
}

请求参数说明:

参数类型说明
idString

数据下行消息ID号,由物联网平台生成,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

versionString协议版本号,目前协议版本号唯一取值为1.0。
paramsObject请求参数,可为空。
methodString请求方法,取值thing.topo.add.notify
deviceNameString子设备的名称。
productKeyString子设备所属产品的ProductKey。

响应参数说明:

参数类型说明
idString消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
codeInteger返回结果,200代表成功。
dataObject请求成功时的返回结果。

通知网关拓扑关系变化

将拓扑关系变化通知网关。

网关订阅Topic:/sys/${productKey}/${deviceName}/thing/topo/change

操作行为通知方式
网关下添加子设备添加网关与子设备的拓扑关系。通知网关。
删除子设备删除子设备与对应网关的拓扑关系。
禁用子设备禁用子设备,并禁用当前子设备与对应网关的拓扑关系。
启用子设备解除子设备禁用,恢复当前子设备和对应网关的拓扑关系。

下行消息Alink数据格式:

{
    "id":"123",
    "version":"1.0",
    "params":{
        "status":0,  //0-创建  1-删除 2-恢复禁用  8-禁用
        "subList":[{
            "productKey":"a1hRrzD****",
            "deviceName":"abcd"
        }]
    }, 
  "method":"thing.topo.change"  
}

参数说明:

参数类型说明
idString

数据下行消息ID号,由物联网平台生成,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。

versionString协议版本号,目前协议版本号唯一取值为1.0。
methodString请求方法,取值thing.topo.change
paramsObject请求参数,包含参数status(拓扑关系状态)和sublist(子设备列表)。
statusInteger拓扑关系状态。
  • 0:创建
  • 1:删除
  • 2:解除禁用(启用)
  • 8:禁用
deviceNameString子设备的名称。
productKeyString子设备所属产品的Key。

Alink响应数据格式:

{
    "id":"123",
    "code":200,
    "message":"success",
    "data":{}
}