跳至主要內容

MQTT对接-网关子设备(网关直连)

BladeX大约 12 分钟deviceprotocol

网关概念

网关在物联网架构中起到桥梁的作用，它连接着物联网设备（子设备）和云端服务器或其他网络服务。网关的主要功能包括：

  • 数据转发：网关负责收集来自子设备的数据，并将数据转发到云平台进行进一步处理和分析。
  • 协议转换：在物联网生态中，不同的设备可能使用不同的通信协议。网关能够将这些不同的协议转换为标准协议，以便数据能够被云平台理解和处理。
  • 安全：网关为子设备提供一个安全层，实现数据加密和身份验证，保护数据在传输过程中的安全。
  • 边缘计算：部分网关具备处理和存储能力，可以在数据发送到云端之前进行初步的数据处理和分析，这种方式称为边缘计算。

子设备概念

子设备是指直接执行物理任务（如感应、控制、监视等）的设备。它们是物联网系统中执行实际操作的终端，通常包括传感器、执行器等。子设备的特点包括：

  • 特定功能：每个子设备通常都有特定的功能，如温度监测、光照检测、运动控制等。
  • 资源受限：许多子设备在计算能力、存储空间和能源消耗方面有限，依赖网关进行数据的聚合和传输。
  • 通信能力：子设备可能通过各种通信技术（如Wi-Fi、蓝牙等）与网关通信。

网关和子设备

一、子设备动态注册

  • 请求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签名校验失败。

二、子设备上下线

说明

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

三、子设备上线

数据上行：

  • 请求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子设备密码或者签名错误。

四、子设备批量上线

数据上行：

  • 请求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子设备密码或者签名错误。

五、子设备下线

数据上行：

  • 请求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子设备会话不存在。

六、子设备批量下线

数据上行：

  • 请求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子设备会话不存在。

七、子设备批量状态上报

数据上行：

  • 请求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子设备密码或者签名错误。
上次编辑于:
贡献者: smallchill