跳至主要內容

协议介绍

BladeX大约 32 分钟introprotocol

一、前言

协议说明

BladeLinks 协议参考阿里云IOT物联网 ALinks 协议设计。初衷是阿里云的设备可以更改 ip 端口就可以接入进来，方便公有云切换到私有服务，大幅降低成本。

二、协议格式

2.1 Topic 格式

重要

BladeLinks 协议在 阿里云 IOT ALink 协议 Topic 之上加了一个 /blade 前缀。

示例（设备属性上报）： /blade/sys/${productKey}/${deviceName}/thing/event/property/post，其中 ${productKey} 和 ${deviceName} 可以在 BladeX 物联平台中 添加设备 获得，还可以通过 设备动态注册 和 子设备动态注册 获取。

响应的 Topic 通常是在请求的 Topic 上添加 _reply，当然也有部分不是这个规则，我们尽量遵循 阿里云ALink 协议。 示例（设备属性上报回复）： /blade/sys/${productKey}/${deviceName}/thing/event/property/post_reply

2.2 请求消息体

示例（设备属性上报）：

{
    "id": "123",
    "version": "1.0",
    "method": "thing.event.property.post",
    "sys":{
        "ack":0
    },
    "params": {
        "Power": {
            "value": "on",
            "time": 1524448722000
        },
        "WF": {
            "value": 23.6,
            "time": 1524448722000
        }
    }
}

请求参数说明：

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。
methodString请求方法。例如：thing.event.property.post。
paramsObject 或 Array请求参数，不通业务的 Topic 结构不同，可能是数组或对象

2.3 响应消息体

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.post",
    "version": "1.0"
}

响应参数说明：

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
codeInteger结果状态码。 具体参考下文设备端通用code。说明物联网平台会对设备上报的属性做校验。通过产品的TSL描述判断上报的属性是否符合定义的属性格式。不合格的属性会直接被过滤掉，并返回失败的错误码。
dataObject请求成功时，返回的数据固定为空。
messageString返回结果信息。请求成功时，返回success。
methodString响应数据对应的请求方法，与请求参数中method相同。
versionString协议版本号，与请求参数中version相同。

三、直连设备

3.1 直连设备上线

mqtt 直连设备，在连接成功和连接断开都会自动触发设备上下线，所以不需要自行处理。

四、网关和子设备

4.1 子设备动态注册

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/sub/register
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/sub/register_reply

说明： 因为子设备通过网关通道与物联网平台通信，Topic 中变量 ${productKey} 和 ${deviceName} 为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "a1234******"
    }
  ],
  "method": "thing.sub.register"
}

响应数据格式：

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "productKey": "a1234******",
      "deviceName": "deviceName1234",
      "deviceSecret": "xxxxxx"
    }
  ]
}

参数说明：

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。重要。如果未配置该功能，则无此参数，云端默认返回响应数据。
paramsList子设备动态注册的参数。
deviceNameString子设备的名称。
productKeyString子设备的产品ProductKey。
deviceSecretString设备密钥。
methodString请求方法，取值thing.sub.register。
codeInteger结果信息。

错误码说明：

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

4.2 子设备上下线

子设备可以逐个上下线，也可以批量上下线。子设备上线之前，需在物联网平台为子设备注册身份，建立子设备与网关的拓扑关系。子设备上线时，物联网平台会根据拓扑关系进行子设备身份校验，以确定子设备是否具备使用网关通道的能力。

4.3 子设备上线

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/combine/login
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/combine/login_reply

说明： 因为子设备通过网关通道与物联网平台通信，Topic 中变量 ${productKey} 和 ${deviceName} 为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234",
    "clientId": "al12345****&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****"
  }
}

说明： 消息体中，参数 productKey 和 deviceName 的值是子设备的对应信息。

请求参数说明：

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参
deviceNameString子设备的设备名称。
productKeyString子设备所属的产品的ProductKey。
signString子设备签名。签名方法与直连设备签名方法相同。签名方法：将所有提交给服务器的参数（sign，signMethod除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。对加签内容，通过signMethod指定的加签算法，并使用设备的DeviceSecret值，进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下： hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒级时间戳。
clientIdString设备端标识。可以为 productKey&deviceName。

响应数据格式：

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
429rate limit, too many subDeviceOnline msg in one minute单个设备认证过于频繁被限流。
428too many subdevices under gateway网关下同时在线子设备过多。
6401topo relation not exist网关和子设备没有拓扑关系。
6100device not found子设备不存在。
521device deleted子设备已被删除。
522device forbidden子设备已被禁用。
6287invalid sign子设备密码或者签名错误。

4.4 子设备批量上线

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/combine/batch_login
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/combine/batch_login_reply

说明： 单次最多可请求50个子设备上线，因为子设备通过网关通道与物联网平台通信，Topic 中变量 ${productKey} 和 ${deviceName} 为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "params":[{
     "productKey": "al12345****", 
     "deviceName": "device1234",
     "clientId": "al12345****&device1234",
     "timestamp": "1581417203000",
     "signMethod": "hmacmd5",
     "sign": "9B9C732412A4F84B981E1AB97CAB****"
  }, {
     "productKey": "al12345****", 
     "deviceName": "device4321",
     "clientId": "al12345****&device4321",
     "timestamp": "1581417203000",
     "signMethod": "hmacmd5",
     "sign": "9B9C732412A4F84B981E1AB97CAB****"
  }]
}

注意

子设备批量上线目前 没校验签名 ，所以最简可以只传 productKey 和 deviceName。

说明

消息体中，参数 productKey 和 deviceName 的值是子设备的对应信息。

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，参数包含要上线的子设备认证参数列表。
deviceNameString子设备的设备名称。
productKeyString子设备所属的产品的ProductKey。
signString子设备签名。签名方法与直连设备签名方法相同。签名方法：将所有提交给服务器的参数（sign，signMethod 和 cleanSession除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。对加签内容，通过signMethod指定的加签算法，并使用设备的DeviceSecret值，进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下： hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒级时间戳。
clientIdString设备端标识。可以为productKey&deviceName。

响应数据格式：

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}

响应参数说明：

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

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
429rate limit, too many subDeviceOnline msg in one minute单个设备认证过于频繁被限流。
428too many subdevices under gateway网关下同时在线子设备过多。
6401topo relation not exist网关和子设备没有拓扑关系。
6100device not found子设备不存在。
521device deleted子设备已被删除。
522device forbidden子设备已被禁用。
6287invalid sign子设备密码或者签名错误。

4.5 子设备下线

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/combine/logout
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/combine/logout_reply

说明： 因为子设备通过网关通道与物联网平台通信，Topic 中变量 ${productKey} 和 ${deviceName} 为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234"
  }
}

说明

消息体中，参数 productKey 和 deviceName 的值是子设备的对应信息。

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，包含要下线的子设备信息。
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

响应数据格式：

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}

响应参数说明：

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

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
520device no session子设备会话不存在。

4.6 子设备批量下线

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/combine/batch_logout
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/combine/batch_logout_reply

说明： 单次最多可请求50个子设备下线，因为子设备通过网关通道与物联网平台通信，Topic 中变量 ${productKey} 和 ${deviceName} 为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "params":[{
            "productKey": "al12345****",
            "deviceName": "device1234"
          },{
            "productKey": "al12345****",
            "deviceName": "device4321"
      }]
}

说明： 消息体中，参数 productKey 和 deviceName 的值是子设备的对应信息。

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，包含要下线的子设备信息。
deviceNameString子设备的设备名称。
productKeyString子设备所属产品的ProductKey。

响应数据格式：

{
  "id":"123",
  "code":"200",
  “message":"success",
  "data":[{
      "productKey": "al12345****"
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}

响应参数说明：

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

错误信息：

错误码消息描述
460request parameter error请求参数错误。
520device no session子设备会话不存在。

4.7 子设备批量状态上报

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/combine/batch_status
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/combine/batch_status_reply

说明： 单次最多可请求50个子设备上报状态，因为子设备通过网关通道与物联网平台通信，Topic 中变量 ${productKey} 和 ${deviceName} 为网关设备的对应信息。

请求数据格式：

{
  "id": "123",
  "params": [{
     "productKey": "al12345****", 
     "deviceName": "device1234",
     "status": "login",
     "clientId": "al12345****&device1234",
     "timestamp": "1581417203000",
     "signMethod": "hmacmd5",
     "sign": "9B9C732412A4F84B981E1AB97CAB****",
  }, {
     "productKey": "al12345****", 
     "deviceName": "device4321",
     "status": "logout",
     "clientId": "al12345****&device4321",
     "timestamp": "1581417203000",
     "signMethod": "hmacmd5",
     "sign": "9B9C732412A4F84B981E1AB97CAB****",
  }]
}

注意

子设备批量状态上报 没校验签名 ，所以最简报文可以只传 productKey 、 deviceName 和 status。

说明

消息体中，参数 productKey 和 deviceName 的值是子设备的对应信息。

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
paramsObject请求入参，参数包含要上线的子设备认证参数列表。
deviceNameString子设备的设备名称。
productKeyString子设备所属的产品的ProductKey。
statusString子设备状态，上线：login、下线：logout。
signString子设备签名。签名方法与直连设备签名方法相同。签名方法：将所有提交给服务器的参数（sign，signMethod 和 cleanSession除外）按照字母顺序排序，然后将参数和值依次拼接（无拼接符号）。对加签内容，通过signMethod指定的加签算法，并使用设备的DeviceSecret值，进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下： hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethodString签名方法，支持hmacSha1、hmacSha256、hmacMd5和Sha256。
timestampString毫秒级时间戳。
clientIdString设备端标识。可以为productKey&deviceName。

响应数据格式：

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234",
      "status": "login"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****",
      "status": "logout"
    }]
}

响应参数说明：

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

错误信息：

错误码错误信息描述
460request parameter error请求参数错误。
429rate limit, too many subDeviceOnline msg in one minute单个设备认证过于频繁被限流。
428too many subdevices under gateway网关下同时在线子设备过多。
6401topo relation not exist网关和子设备没有拓扑关系。
6100device not found子设备不存在。
521device deleted子设备已被删除。
522device forbidden子设备已被禁用。
6287invalid sign子设备密码或者签名错误。

五、代理通信

重要

有些场景对于一些第三方的设备，使用直连或网关都不太适合，这种情况下可以使用 BladeX 物联网平台 中的 mqtt 模块中生成 mqtt 超级账号，转发或协议转换规则等处理大量的设备上下线或者设备数据的接入。

5.1 设备上线

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/login
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/login_reply

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "method": "ext.session.login"
}

说明

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。

响应数据格式：

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

响应参数说明：

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

5.2 设备下线

数据上行：

  • 请求Topic：/blade/ext/session/${productKey}/${deviceName}/logout
  • 响应Topic：/blade/ext/session/${productKey}/${deviceName}/logout_reply

请求数据格式：

{
  "id": "123",
  "version": "1.0",
  "method": "ext.session.logout"
}

参数说明

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。

响应数据格式：

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

响应参数说明：

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

六、设备属性、事件、服务

6.1 设备上报属性

数据上行：

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/post
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/post_reply

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "method": "thing.event.property.post",
    "sys":{
        "ack":0
    },
    "params": {
        "Power": {
            "value": "on",
            "time": 1524448722000
        },
        "WF": {
            "value": 23.6,
            "time": 1524448722000
        },
        "COLOUR": "RED"
    }
}

请求数据格式：

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。
methodString请求方法。例如： thing.event.property.post。
paramsObject请求参数。如以上示例中，设备上报了的两个属性Power（电源）和WF（工作电流）的信息。具体属性信息，包含属性上报时间（time）和上报的属性值（value）。若仅传入属性值，无需上传字段time和value，params示例如下： "params": { "Power": "on", "WF": 23.6 }如果是自定义模块属性，属性标识符格式为${模块标识符}:${属性标识符}（中间为英文冒号）。例如： "test:Power": { "value": "on", "time": 1524448722000 }
timeLong属性上报时间戳，类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。若上传 time，物联网平台的云端保存上传的时间作为属性上报时间。若不上传 time，物联网平台的云端自动生成属性上报时间并保存。
valueObject上报的属性值。若不上传 time，可不上传 value，直接上传参数值即可。

响应数据格式：

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

响应参数说明：

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

6.2 设置设备属性

数据下行（平台发送、设备监听）：

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/service/property/set
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/service/property/set_reply

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "method": "thing.service.property.set",
    "params": {
        "Temperature": "30.5"
    }
}

参数说明

参数类型说明
idString消息ID号，String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
paramsObject属性设置参数。如以上示例中，设置属性：{ "Temperature": "30.5" }。如果是自定义模块属性，属性标识符格式为${模块标识符}:${属性标识符}（中间为英文冒号），例如{ "test:temperature": "30.5" }。
methodString请求方法。例如：thing.service.property.set。

响应数据格式：

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

响应参数说明：

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

6.3 设备上报事件

数据上行：

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post_reply

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "method": "thing.event.${tsl.event.identifier}.post",
    "sys":{
        "ack":0
    },
    "params": {
        "value": {
            "Power": "on",
            "WF": "2"
        },
        "time": 1524448722000
    }
}

参数说明

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。
methodString请求方法。默认模块取值为thing.event.${tsl.event.identifier}.post。自定义模块取值为thing.event.${tsl.functionBlockId}:${tsl.event.identifier}.post。说明${tsl.event.identifier}为物模型中定义的事件标识符，${tsl.functionBlockId}为自定义模块的标识符。
paramsObject上报事件的输出参数。
valueObject事件的输出参数信息。如以上示例中的两个参数Power（电源）和WF（工作电流）的信息。 { "Power": "on", "WF": "2" }
timeLong事件上报的时间戳，类型为UTC毫秒级时间。该参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。若上传time，物联网平台的云端保存上传的时间作为事件上报时间。若不上传time，物联网平台的云端自动生成事件上报时间并保存。

响应数据格式：

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

响应参数说明：

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

6.4 网关批量上报数据

数据上行：

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/pack/post
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/pack/post_reply

请求数据格式：

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "method": "thing.event.property.pack.post",
    "params": {
        "properties": {
            "Power": {
                "value": "on",
                "time": 1524448722000
            },
            "WF": {
                "value": 23.6,
                "time": 1524448722000
            }
        },
        "events": {
            "alarmEvent1": {
                "value": {
                    "param1": "on",
                    "param2": "2"
                },
                "time": 1524448722000
            },
            "alertEvent2": {
                "value": {
                    "param1": "on",
                    "param2": "2"
                },
                "time": 1524448722000
            }
        },
        "subDevices": [
            {
                "identity": {
                    "productKey": "",
                    "deviceName": ""
                },
                "properties": {
                    "Power": {
                        "value": "on",
                        "time": 1524448722000
                    },
                    "WF": {
                        "value": 23.6,
                        "time": 1524448722000
                    }
                },
                "events": {
                    "alarmEvent1": {
                        "value": {
                            "param1": "on",
                            "param2": "2"
                        },
                        "time": 1524448722000
                    },
                    "alertEvent2": {
                        "value": {
                            "param1": "on",
                            "param2": "2"
                        },
                        "time": 1524448722000
                    }
                }
            }
        ]
    }
}

参数说明

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。
paramsObject请求参数。
propertiesObject属性，包含属性标识符、属性值value和属性生成的时间time。其中，time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。如以上示例中，设备上报了的两个属性Power（电源）和WF（工作电流）的信息。如果是自定义模块属性，属性标识符格式为${模块标识符}:${属性标识符}（中间为英文冒号）。例如： "test:Power": { "value": "on", "time": 1524448722000 }
eventsObject事件，包含事件标识符、事件输出参数value和事件生成的时间time。其中，time参数为可选字段。根据您的业务场景决定消息中是否带时间戳。如果消息频繁，需根据时间戳判断消息顺序，建议消息中带有时间戳。如以上示例中，上报了两个事件alarmEvent1（告警事件1）和alarmEvent2（告警事件2），及对应事件参数param1和param2的信息。如果是自定义模块事件，事件标识符格式为${模块标识符}:${事件标识符}（中间为英文冒号）。例如： "test:alarmEvent1": { "value": { "param1": "on", "param2": "2" }, "time": 1524448722000 }
subDevicesObject子设备信息。
productKeyString子设备产品的Productkey。
deviceNameString子设备名称。
methodString请求参数。取值：thing.event.property.pack.post。

响应数据格式：

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

响应参数说明：

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

6.5 物模型历史数据上报

数据上行：

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/history/post
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/history/post_reply

请求数据格式：

{
    "id": "123", 
    "version": "1.0",
    "sys":{
        "ack":0
    }, 
    "method": "thing.event.property.history.post", 
    "params": [
        {
            "identity": {
                "productKey": "", 
                "deviceName": ""
            }, 
            "properties": [
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }, 
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }
            ], 
            "events": [
                {
                    "alarmEvent": {
                        "value": {
                            "Power": "on", 
                            "WF": "2"
                        }, 
                        "time": 1524448722000
                    }, 
                    "alertEvent": {
                        "value": {
                            "Power": "off", 
                            "WF": "3"
                        }, 
                        "time": 1524448722000
                    }
                }
            ]
        }, 
        {
            "identity": {
                "productKey": "xxx", 
                "deviceName": ""
            }, 
            "properties": [
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }
            ], 
            "events": [
                {
                    "alarmEvent": {
                        "value": {
                            "Power": "on", 
                            "WF": "2"
                        }, 
                        "time": 1524448722000
                    }, 
                    "alertEvent": {
                        "value": {
                            "Power": "off", 
                            "WF": "3"
                        }, 
                        "time": 1524448722000
                    }
                }
            ]
        }
    ]
}

参数说明

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。
methodString请求方法。取固定值：thing.event.property.history.post。
paramsObject请求参数。
identityString数据所属设备的身份证书信息，包含参数productKey和deviceName。说明直连设备仅能上报自己的物模型历史数据。网关设备可以上报其子设备的物模型历史数据。网关上报子设备历史数据时，identity为子设备的信息。
propertiesObject属性，包含属性标识符、属性值value和属性生成的时间time。如以上示例中，设备上报了的两个属性Power（电源）和WF（工作电流）的历史信息。如果是自定义模块属性，属性标识符格式为${模块标识符}:${属性标识符}（中间为英文冒号）。例如： "test:Power": { "value": "on", "time": 1524448722000 }
eventsObject事件，包含事件标识符、事件输出参数value和事件生成的时间time。如以上示例中，上报了事件alarmEvent（告警事件）及对应事件参数Power（电源）和WF（工作电流）的历史信息。如果是自定义模块事件，事件标识符格式为${模块标识符}:${事件标识符}（中间为英文冒号）。例如： "test:alarmEvent": { "value": { "Power": "on", "WF": "2" }, "time": 1524448722000 }

响应数据格式：

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

响应参数说明：

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

6.6 设备批量上报属性、事件

数据上行：

  • 请求Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/batch/post
  • 响应Topic：/blade/sys/${productKey}/${deviceName}/thing/event/property/batch/post_reply

请求数据格式：

{
    "id": "123", 
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "method": "thing.event.property.batch.post",
    "params": {
        "properties": {
            "Power": [
                {
                    "value": "on", 
                    "time": 1524448722000
                },
                {
                    "value": "off", 
                    "time": 1524448722001
                }
            ], 
            "WF": [
                {
                    "value": 3, 
                    "time": 1524448722000
                },
                {
                    "value": 4, 
                    "time": 1524448722009
                }
            ]
        }, 
        "events": {
            "alarmEvent": [
                {
                    "value": {
                        "Power": "on", 
                        "WF": "2"
                    }, 
                    "time": 1524448722000
                },
                {
                    "value": {
                        "Power": "on", 
                        "WF": "2"
                    }, 
                    "time": 1524448722000
                }
            ]
        }
    }
}

参数说明

参数类型说明
idString消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
versionString协议版本号，目前协议版本号唯一取值为1.0。
sysObject扩展功能的参数，其下包含各功能字段。 说明使用设备端SDK开发时，如果未设置扩展功能，则无此参数，相关功能保持默认配置。
ackIntegersys下的扩展功能字段，表示是否返回响应数据。1：云端返回响应数据。0：云端不返回响应数据。
methodString请求方法。取固定值：thing.event.property.batch.post。
paramsObject请求参数。
propertiesObject属性，包含属性标识符、属性值 value 和属性生成的时间 time。如以上示例中，设备上报了的两个属性Power（电源）和WF（工作电流）的批量信息。如果是自定义模块属性，属性标识符格式为${模块标识符}:${属性标识符}（中间为英文冒号）。例如： "test:Power": { "value": "on", "time": 1524448722000 }
eventsObject事件，包含事件标识符、事件输出参数 value和事件生成的时间 time。如以上示例中，上报了事件alarmEvent（告警事件）及对应事件参数Power（电源）和WF（工作电流）的批量信息。如果是自定义模块事件，事件标识符格式为${模块标识符}:${事件标识符}（中间为英文冒号）。例如： "test:alarmEvent": { "value": { "Power": "on", "WF": "2" }, "time": 1524448722000 }

响应数据格式：

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

响应参数说明：

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

七、设备上报与下发(HTTP)

重要

平台原生协议为MQTT，除此以外还对对MQTT协议进行了部分HTTP封装，让开发者可以通过更便捷的HTTP方式与设备进行通信。当调用HTTP接口时，物联网平台会将HTTP请求转换为对应的MQTT消息。 平台将消息通过MQTT协议发送给指定的设备，对于同步接口，平台会等待设备通过MQTT返回响应后，再将结果通过HTTP响应返回给调用方。

适用场景

  • 后台管理系统对设备进行控制
  • 第三方系统集成时需要调用设备
  • 不方便直接使用MQTT协议的场景
  • 需要同步获取设备响应的场景

7.1 服务端通用消息下发

  • 请求路径：https://${域名}/blade-broker/device/mqtt/publish
  • 请求方式：POST
  • 接口描述：向指定设备发送MQTT消息

请求参数：

{
  "productKey": "E7N1cQPFik5",     
  "deviceName": "KxCiFW8VYc0s66aJ",  
  "topic": "/blade/sys/E7N1cQPFik5/KxCiFW8VYc0s66aJ/thing/event/property/post",   
  "payload": {
    "id": "123",
    "version": "1.0",
    "method": "thing.event.property.post",
    "sys":{
      "ack":0
    },
    "params": {
      "Power": {
        "value": "on",
        "time": 1524448722000
      },
      "Temperature": "30.5",
      "Humidity": "45"
    }
  }
}

参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称
topicString是MQTT消息主题
payloadObject是消息内容

响应示例：

{
  "code": 200,          
  "success": true,      
  "data": {},         
  "msg": "操作成功"     
}

7.2 服务端设置设备属性

  • 请求路径：https://${域名}/blade-broker/device/mqtt/property/set
  • 请求方式：POST
  • 接口描述：设置设备属性值

请求参数：

{
  "productKey": "E7N1cQPFik5",     
  "deviceName": "KxCiFW8VYc0s66aJ",   
  "params": {                 
    "Temperature": "30.5"
  }
}

参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称
paramsMap是属性参数键值对

响应示例：

{
  "code": 200,          
  "success": true,      
  "data": {},         
  "msg": "操作成功"     
}

7.3 服务端同步设置设备属性

  • 请求路径：https://${域名}/blade-broker/device/mqtt/property/set/sync
  • 请求方式：POST
  • 接口描述：同步设置设备属性值，等待设备响应

请求参数：

{
  "productKey": "E7N1cQPFik5",     
  "deviceName": "KxCiFW8VYc0s66aJ",   
  "params": {                 
    "Temperature": "30.5"
  }
}

参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称
paramsMap是属性参数键值对

响应示例：

{
  "code": 200,
  "success": true,
  "data": {
    "id": "xxxxx",
    "version": "1.0",
    "code": 200,
    "message": "success",
    "method": "property.set",
    "data": {
      "Temperature": "30.5",
      "Humidity": "45"
    }
  },
  "msg": "操作成功"
}

7.4 服务端同步获取设备属性

  • 请求路径：https://${域名}/blade-broker/device/mqtt/property/get/sync
  • 请求方式：POST
  • 接口描述：同步获取设备当前属性值

请求参数：

{
  "productKey": "E7N1cQPFik5",     
  "deviceName": "KxCiFW8VYc0s66aJ",   
  "params": [                 
    "Temperature",
    "Humidity"
  ]
}

参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称
paramsList String是属性标识符列表

响应示例：

{
  "code": 200,
  "success": true,
  "data": {
    "id": "xxxxxx",
    "version": "1.0",
    "code": 200,
    "message": "success",
    "method": "property.get",
    "data": {
      "Temperature": "30.5",
      "Humidity": "45"
    }
  },
  "msg": "操作成功"
}

同步接口注意事项

  1. 所有同步接口默认超时时间为5秒
  2. 当设备离线或未响应时，接口会返回超时错误
  3. 属性标识符需要与物模型中定义的一致
  4. 自定义模块的属性标识符格式为${模块标识符}:${属性标识符}

7.5 设备端属性数据上报

  • 接口路径：https://${域名}/blade-iot/openapi/thing/sys/{productKey}/{deviceName}/thing/property/post
  • 请求方式：POST
  • 接口描述：设备向平台上报属性数据

路径参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称

请求参数：

{
    "id": "xxxxxxxx",             
    "version": "1.0",             
    "sys": {
        "ack": 0                  
    },
    "method": "thing.property.post",  
    "params": {                    
        "Temperature": 30.5,
        "Humidity": 65
    }
}

响应示例：

{
    "id": "xxxxxxxx",
    "version": "1.0",
    "code": 200,
    "message": "success",
    "method": "thing.property.post",
    "data": {},
    "resultCode": {
        "code": 200,
        "message": "success"
    }
}

7.6 设备端事件数据上报

  • 接口路径：https://${域名}/blade-iot/openapi/thing/sys/{productKey}/{deviceName}/thing/event/{identifier}/post
  • 请求方式：POST
  • 接口描述：设备向平台上报事件数据

路径参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称
identifierString是事件标识符

请求参数：

{
    "id": "xxxxxxxx",
    "version": "1.0",
    "sys": {
        "ack": 0
    },
    "method": "thing.event.{identifier}.post",
    "params": {
        "value": 100,
        "time": 1516517974000
    }
}

响应示例：

{
    "id": "xxxxxxxx",
    "version": "1.0",
    "code": 200,
    "message": "success",
    "method": "thing.event.{identifier}.post",
    "data": {},
    "resultCode": {
        "code": 200,
        "message": "success"
    }
}

7.7 设备端命令响应数据上报

  • 接口路径：https://${域名}/blade-iot/openapi/thing/sys/{productKey}/{deviceName}/thing/command/{identifier}/post
  • 请求方式：POST
  • 接口描述：设备上报命令执行的响应结果

路径参数说明：

参数类型是否必填说明
productKeyString是产品唯一标识
deviceNameString是设备名称
identifierString是命令标识符

请求参数：

{
    "id": "xxxxxxxx",
    "version": "1.0",
    "sys": {
        "ack": 0
    },
    "method": "thing.command.{identifier}.post",
    "params": {
        "result": "success",
        "data": {}
    }
}

响应示例：

{
    "id": "xxxxxxxx",
    "version": "1.0",
    "code": 200,
    "message": "success",
    "method": "thing.command.{identifier}.post",
    "data": {},
    "resultCode": {
        "code": 200,
        "message": "success"
    }
}

注意事项

  1. 所有的请求必须包含完整的消息ID和版本号
  2. 事件和命令的identifier需要与物模型中定义的标识符一致
  3. 响应中的code为200表示成功，其他值表示失败
  4. 建议在进行设备开发时，先在平台定义好物模型，再进行接口调用

八、NTP服务

重要

BladeX 物联网平台提供NTP服务，为资源受限的嵌入式设备，解决无法实时地获取服务端时间的问题。

8.1 原理介绍

物联网平台的NTP服务，借鉴NTP协议原理，将物联网平台作为NTP服务器。高精准度的时间校正流程如下：

  1. 设备端通过指定Topic向物联网平台发送消息，会携带发送时间 deviceSendTime。
  2. 物联网平台接收设备端消息后，回复消息中，会增加接收消息的时间 serverRecvTime 和回复消息的时间 serverSendTime。
  3. 设备端接收到物联网平台回复，会根据本地时间，给出接收回复的时间 deviceRecvTime。
  4. 根据以上出现的4个时间，计算设备端与物联网平台的时间差，得出设备端获取到的，服务端当前的精确时间 Time。

提示

仅当设备端成功接入物联网平台后，才能通过NTP服务进行时间校准。

通信 Topic

请求Topic：/blade/ext/ntp/${productKey}/${deviceName}/request

响应Topic：/blade/ext/ntp/${productKey}/${deviceName}/response

8.2 设备端接入说明

NTP服务使用流程，及其Topic说明如下：

  1. 设备端向Topic：/blade/ext/ntp/${productKey}/${deviceName}/request 发送一条QoS=0的消息，携带设备当前的时间戳，单位为毫秒。示例如下：

    {
    "deviceSendTime":"1571724098000"
}

    说明

    • 时间戳数字，支持Long（默认）和String类型。
    • NTP服务目前仅支持QoS=0的消息。

  2. 设备端通过订阅Topic：/blade/ext/ntp/${productKey}/${deviceName}/response，收到物联网平台回复的消息，包含以下信息。

    {
    "deviceSendTime":"1571724098000",
    "serverRecvTime":"1571724098110",
    "serverSendTime":"1571724098115"
}

  3. 设备端计算出服务端当前精确的Unix时间。

    假设基于请求的时延和响应的时延相同，设备端收到服务端的时间即${deviceRecvTime}，则设备上的精确时间为：(${serverRecvTime}+${serverSendTime}+${deviceRecvTime}-${deviceSendTime})/2。

8.3 使用示例

提示

设备端和服务端发送的时间戳数据的类型相同。例如，设备端传的时间戳是String类型，服务端返回的时间戳也是String类型。

例如，设备上时间是1571724098000毫秒，服务端时间是1571724098100毫秒，链路延时是10毫秒，服务端从接收到发送间隔为5毫秒。

操作设备端时间（毫秒）服务端时间（毫秒）
设备端发送1571724098000（deviceSendTime）1571724098100
服务端接收15717240980101571724098110（serverRecvTime）
服务端发送15717240980151571724098115（serverSendTime）
设备端接收1571724098025（deviceRecvTime）1571724098125

则设备端计算出的当前准确时间为(1571724098110+1571724098115+1571724098025-1571724098000)毫秒÷2=1571724098125毫秒。

如果直接采用物联网平台返回的时间戳，只能得到时间1571724098115毫秒，与服务端上的时间会有10毫秒的链路延时误差。

九、设备端通用code

提示

设备通用code信息，用于表达云端下行推送时设备侧业务处理的返回结果。

错误码消息描述
200success请求成功。
400request error内部服务错误， 处理时发生内部错误
460request parameter error请求参数错误， 设备入参校验失败
429too many requests请求过于频繁，设备端处理不过来时可以使用
100000-110000自定义的错误信息从100000到110000的错误码用于设备自定义错误信息，和云端错误信息加以区分
上次编辑于:
贡献者: smallchill