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

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

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

添加设备拓扑关系

网关类型的设备，可以通过该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"
    }
  ]
}

请求参数说明：

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

如果未配置该功能，则无此参数，云端默认返回响应数据。
params List 请求入参。
deviceName String 子设备的名称。
productKey String 子设备所属产品的ProductKey。
sign String

签名。

加签算法：

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

响应参数说明：

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

错误信息：

错误码 消息 描述
460 request parameter error 请求参数错误。
6402 topo relation cannot add by self 设备不能把自己添加为自己的子设备。
401 request 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"
    }
  ]
}

请求参数说明：

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

如果未配置该功能，则无此参数，云端默认返回响应数据。
params List 请求参数。
deviceName String 子设备名称。
productKey String 子设备所属产品的ProductKey
method String 请求方法。取值thing.topo.delete。

响应参数说明：

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

错误信息：

错误码 消息 描述
460 request parameter error 请求参数错误。
6100 device 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"
    }
  ]
}

请求参数说明：

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

如果未配置该功能，则无此参数，云端默认返回响应数据。
params Object 请求参数，可为空。
method String 请求方法，取值thing.topo.get。

响应参数说明：

参数 类型 说明
id String 消息ID，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
code Integer 返回结果，200代表成功。
data Object 请求成功时的返回结果。
deviceName String 子设备的名称。
productKey String 子设备所属产品的ProductKey。

错误信息：

错误码 消息 描述
460 request 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":{}
}

请求参数说明：

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

如果未配置该功能，则无此参数，云端默认返回响应数据。
params Object 请求参数，可为空。
method String 请求方法，取值thing.list.found。
deviceName String 子设备的名称。
productKey String 子设备所属产品的ProductKey。

响应参数说明：

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

错误信息：

错误码 消息 描述
460 request parameter error 请求参数错误。
6250 product not found 上报的子设备产品不存在。
6280 devicename 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": {}
}

请求参数说明：

参数 类型 说明
id String

数据下行消息ID号，由物联网平台生成，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version String 协议版本号，目前协议版本号唯一取值为1.0。
params Object 请求参数，可为空。
method String 请求方法，取值thing.topo.add.notify。
deviceName String 子设备的名称。
productKey String 子设备所属产品的ProductKey。

响应参数说明：

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

通知网关拓扑关系变化

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

网关订阅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"  
}

参数说明：

参数 类型 说明
id String

数据下行消息ID号，由物联网平台生成，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version String 协议版本号，目前协议版本号唯一取值为1.0。
method String 请求方法，取值thing.topo.change。
params Object 请求参数，包含参数status（拓扑关系状态）和sublist（子设备列表）。
status Integer 拓扑关系状态。
  • 0：创建
  • 1：删除
  • 2：解除禁用（启用）
  • 8：禁用
deviceName String 子设备的名称。
productKey String 子设备所属产品的Key。

Alink响应数据格式：

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