MQTT对接-网关子设备(网关直连)
网关概念
网关在物联网架构中起到桥梁的作用,它连接着物联网设备(子设备)和云端服务器或其他网络服务。网关的主要功能包括:
- 数据转发:网关负责收集来自子设备的数据,并将数据转发到云平台进行进一步处理和分析。
- 协议转换:在物联网生态中,不同的设备可能使用不同的通信协议。网关能够将这些不同的协议转换为标准协议,以便数据能够被云平台理解和处理。
- 安全:网关为子设备提供一个安全层,实现数据加密和身份验证,保护数据在传输过程中的安全。
- 边缘计算:部分网关具备处理和存储能力,可以在数据发送到云端之前进行初步的数据处理和分析,这种方式称为边缘计算。
子设备概念
子设备是指直接执行物理任务(如感应、控制、监视等)的设备。它们是物联网系统中执行实际操作的终端,通常包括传感器、执行器等。子设备的特点包括:
- 特定功能:每个子设备通常都有特定的功能,如温度监测、光照检测、运动控制等。
- 资源受限:许多子设备在计算能力、存储空间和能源消耗方面有限,依赖网关进行数据的聚合和传输。
- 通信能力:子设备可能通过各种通信技术(如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"
}
]
}
参数说明:
参数 | 类型 | 说明 |
---|---|---|
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。 |
deviceSecret | String | 设备密钥。 |
method | String | 请求方法,取值thing.sub.register 。 |
code | Integer | 结果信息。 |
错误码说明:
错误码 | 消息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
6402 | topo relation cannot add by self | 设备不能将自己添加为自己的子设备。 |
401 | request 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 的值是子设备的对应信息。
请求参数说明:
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
params | Object | 请求入参 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属的产品的ProductKey。 |
sign | String | 子设备签名。签名方法与直连设备签名方法相同。签名方法:将所有提交给服务器的参数(sign,signMethod除外)按照字母顺序排序,然后将参数和值依次拼接(无拼接符号)。对加签内容,通过signMethod指定的加签算法,并使用设备的DeviceSecret值,进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下: hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000) |
signMethod | String | 签名方法,支持hmacSha1、hmacSha256、hmacMd5和Sha256。 |
timestamp | String | 毫秒级时间戳。 |
clientId | String | 设备端标识。可以为 productKey&deviceName 。 |
响应数据格式:
{
"id":"123",
"code":200,
"message":"success"
"data":{
"deviceName": "device1234",
"productKey": "al12345****"
}
}
错误信息:
错误码 | 错误信息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
429 | rate limit, too many subDeviceOnline msg in one minute | 单个设备认证过于频繁被限流。 |
428 | too many subdevices under gateway | 网关下同时在线子设备过多。 |
6401 | topo relation not exist | 网关和子设备没有拓扑关系。 |
6100 | device not found | 子设备不存在。 |
521 | device deleted | 子设备已被删除。 |
522 | device forbidden | 子设备已被禁用。 |
6287 | invalid 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 的值是子设备的对应信息。
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
params | Object | 请求入参,参数包含要上线的子设备认证参数列表。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属的产品的ProductKey。 |
sign | String | 子设备签名。签名方法与直连设备签名方法相同。签名方法:将所有提交给服务器的参数(sign,signMethod 和 cleanSession除外)按照字母顺序排序,然后将参数和值依次拼接(无拼接符号)。对加签内容,通过signMethod指定的加签算法,并使用设备的DeviceSecret值,进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下: hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000) |
signMethod | String | 签名方法,支持hmacSha1、hmacSha256、hmacMd5和Sha256。 |
timestamp | String | 毫秒级时间戳。 |
clientId | String | 设备端标识。可以为productKey&deviceName 。 |
响应数据格式:
{
"id":"123",
"code":"200",
"message":"success",
"data":[{
"productKey": "al12345****",
"deviceName": "device1234"
},{
"deviceName": "device4321",
"productKey": "al12345****"
}]
}
响应参数说明:
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 返回结果,200代表成功。 |
message | String | 返回结果信息。 |
data | Object | 请求成功或失败时返回的子设备信息。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属产品的密钥。 |
错误信息:
错误码 | 错误信息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
429 | rate limit, too many subDeviceOnline msg in one minute | 单个设备认证过于频繁被限流。 |
428 | too many subdevices under gateway | 网关下同时在线子设备过多。 |
6401 | topo relation not exist | 网关和子设备没有拓扑关系。 |
6100 | device not found | 子设备不存在。 |
521 | device deleted | 子设备已被删除。 |
522 | device forbidden | 子设备已被禁用。 |
6287 | invalid 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 的值是子设备的对应信息。
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
params | Object | 请求入参,包含要下线的子设备信息。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属产品的ProductKey。 |
响应数据格式:
{
"id": "123",
"code": 200,
"message": "success",
"data": {
"deviceName": "device1234",
"productKey": "al12345****"
}
}
响应参数说明:
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 返回结果,200代表成功。 |
message | String | 返回结果信息。 |
data | Object | 请求成功或失败时,返回的下线的子设备信息。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属产品的ProductKey。 |
错误信息:
错误码 | 错误信息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
520 | device 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 的值是子设备的对应信息。
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
params | Object | 请求入参,包含要下线的子设备信息。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属产品的ProductKey。 |
响应数据格式:
{
"id":"123",
"code":"200",
“message":"success",
"data":[{
"productKey": "al12345****"
"deviceName": "device1234"
},{
"deviceName": "device4321",
"productKey": "al12345****"
}]
}
响应参数说明:
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 返回结果,200代表成功。 |
message | String | 返回结果信息。 |
data | Object | 请求成功或失败时,返回的下线的子设备信息。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属产品的ProductKey。 |
错误信息:
错误码 | 消息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
520 | device 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 的值是子设备的对应信息。
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
params | Object | 请求入参,参数包含要上线的子设备认证参数列表。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属的产品的ProductKey。 |
status | String | 子设备状态,上线:login、下线:logout。 |
sign | String | 子设备签名。签名方法与直连设备签名方法相同。签名方法:将所有提交给服务器的参数(sign,signMethod 和 cleanSession除外)按照字母顺序排序,然后将参数和值依次拼接(无拼接符号)。对加签内容,通过signMethod指定的加签算法,并使用设备的DeviceSecret值,进行签名计算。计算结果作为sign的取值。sign值计算方法示例如下: hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000) |
signMethod | String | 签名方法,支持hmacSha1、hmacSha256、hmacMd5和Sha256。 |
timestamp | String | 毫秒级时间戳。 |
clientId | String | 设备端标识。可以为productKey&deviceName 。 |
响应数据格式:
{
"id":"123",
"code":"200",
"message":"success",
"data":[{
"productKey": "al12345****",
"deviceName": "device1234",
"status": "login"
},{
"deviceName": "device4321",
"productKey": "al12345****",
"status": "logout"
}]
}
响应参数说明:
参数 | 类型 | 说明 |
---|---|---|
id | String | 消息ID,String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 |
code | Integer | 返回结果,200代表成功。 |
message | String | 返回结果信息。 |
data | Object | 请求成功或失败时返回的子设备信息。 |
deviceName | String | 子设备的设备名称。 |
productKey | String | 子设备所属产品的密钥。 |
错误信息:
错误码 | 错误信息 | 描述 |
---|---|---|
460 | request parameter error | 请求参数错误。 |
429 | rate limit, too many subDeviceOnline msg in one minute | 单个设备认证过于频繁被限流。 |
428 | too many subdevices under gateway | 网关下同时在线子设备过多。 |
6401 | topo relation not exist | 网关和子设备没有拓扑关系。 |
6100 | device not found | 子设备不存在。 |
521 | device deleted | 子设备已被删除。 |
522 | device forbidden | 子设备已被禁用。 |
6287 | invalid sign | 子设备密码或者签名错误。 |