HanClouds MQTT标准协议

MQTT协议

序号	MQTT topic名称	方向	描述
1	rsp/welcome	云端下发	设备成功连接平台，云端下发欢迎消息
2	initack/{deviceKey}	设备上报	设备通知云端，其已经收到了初始化的鉴权参数，之后云端就不会再传递该设备的鉴权参数
3	data/{deviceKey}/{stream}	设备上报	设备上传数据流
4	event/{deviceKey}/{identifier}	设备上报	设备上传事件
5	ctl/{deviceKey}/{commandId}/{identifier}	云端下发	云端下发模型命令
6	cmd/{deviceKey}/{commandId}/{dataType}	云端下发	云端下发自定义命令
7	cmdack/{deviceKey}/{commandId}	设备上报	设备上传命令回复
8	direct/{deviceKey}/{stream}	云端下发	设备透传数据的下发
9	proxy/structureUp	设备上报	网关上传设备拓扑关系，返回全部子设备
10	proxy/structureUpOnly	设备上报	网关上传设备拓扑关系，只返回所上传子设备
11	sync/{deviceKey}/structure	云端下发	云端下发设备拓扑关系
12	proxy/structureGet	设备上报	网关请求云端查询拓扑关系
13	proxy/structureStatus	设备上报	网关代理子设备上下线
14	rsp/proxy/notify	云端下发	云端下发子设备上下线结果
15	api/setDeviceInfo	设备上报	通过MQTT修改设备信息
16	api/setCardInfo	设备上报	通过MQTT设置设备与物联卡的关系
17	api/setparent	设备上报	网关向云端上传拓扑结构，只涉及网络拓扑图的绘制

云端下发欢迎消息

topic：rsp/welcome

payload说明：

{
 "deviceKey": "7f686df08b024bc0aecad425ed938cda",
 "deviceSecret": "sUqce0YaMSF3bkUR",
 "queryToken": "vmjYltdPbehsuTcE",
 "cmdToken": "adtDooXp9Yf0Bgxn",
 "uploadToken": "rMDQ6ogz3A6QdqrD",
 "time": 1657778205687,
 "dynamicSecret": "STsoJnI0U3tWWDR6ZytrKSrNPcWRgEO4Pksr070ELhny5wTZDgjl5aCiHUdomAgP"
}

参数说明：

参数	类型	说明	必选	备注
deviceKey	String	平台自动生成，做为设备在平台的唯一标识	是
deviceSecret	String	平台上传数据时，对数据进行加密传输	是
queryToken	String	用于在通过http查询设备历史数据时进行鉴权	是
cmdToken	String	用于在通过http向设备下发命令时鉴权	是
uploadToken	String	用于在通过http向设备上传数据时进行鉴权	是
time	long	下发消息时的时间戳	是
dynamicSecret	String	设备以签名模式连接平台时，后续用于加密payload数据的密钥	否

上传初始化完成消息

topic：initack/{deviceKey}

• deviceKey为当前设备的deviceKey

payload说明：

可以为null，当前topic的payload不具备任何意义

上传数据流

topic：data/{deviceKey}/{stream}

• deviceKey必须为本设备的deviceKey，网关代理的子设备上传数据流时，deviceKey为子设备的deviceKey
• stream为物模型定义的数据流标识符

payload说明：

• payload需匹配定义的数据流模型，否则平台会断开与设备的连接
• payload在签名模式下为用dynamicSecret加密的密文，在非签名模式下为数据明文

上传事件

topic：event/{deviceKey}/{identifier}

• deviceKey必须为本设备的deviceKey，网关代理的子设备上传事件时，deviceKey为子设备的deviceKey
• identifier为物模型定义的事件标识符

payload说明：

• payload需匹配定义的事件模型，否则平台会断开与设备的连接
• payload在签名模式下为用dynamicSecret加密的密文，在非签名模式下为数据明文

云端下发模型命令

topic：ctl/{deviceKey}/{commandId}/{identifier}

• deviceKey必须为在线设备的deviceKey，如果设备不在线，且在命令有效时间内设备没有上线，命令就会过期，即下发失败
• commandId为命令的唯一标识
• identifier为物模型定义的命令标识符

payload说明：

• payload在签名模式下为用dynamicSecret加密的密文，在非签名模式下为数据明文

云端下发自定义命令

topic：cmd/{deviceKey}/{commandId}/{dataType}

• deviceKey必须为在线设备的deviceKey，如果设备不在线，且在命令有效时间内设备没有上线，命令就会过期，即下发失败
• commandId为命令的唯一标识
• dataType为命令数据所属类型，共5种：JSON、INT、STRING、DOUBLE、BIN

payload说明：

• payload在签名模式下为用dynamicSecret加密的密文，在非签名模式下为数据明文

上传命令回复

topic：cmdack/{deviceKey}/{commandId}

• deviceKey必须为本设备的deviceKey，网关代理的子设备上传命令回复时，deviceKey为子设备的deviceKey
• commandId为云端下发命令时携带的命令的唯一标识

payload说明：

• payload需匹配定义的命令模型，否则平台会断开与设备的连接
• payload在签名模式下为用dynamicSecret加密的密文，在非签名模式下为数据明文

数据透传

topic：direct/{deviceKey}/{stream}

• deviceKey为数据来源设备的deviceKey
• stream为物模型定义的数据流标识符

payload说明：

{data}

• data为数据来源设备上传的数据

网关上传拓扑关系

topic：proxy/structureUp或proxy/structureUpOnly

payload说明：

{
  "slaveDeviceSn": ["sn1","sn2"]
}

参数说明：

参数	类型	说明	必选	备注
slaveDeviceSn	array	网关下子设备sn号集合	是

云端下发拓扑关系

topic：sync/{deviceKey}/structure

• deviceKey为网关的deviceKey

payload说明：

 [
   {"slaveDeviceKey":"slaveKey01","sn":"sn01"},
   {"slaveDeviceKey":"slaveKey02","sn":"sn02"},...
 ]

参数说明：

参数	类型	说明	必选	备注
slaveDeviceKey	String	子设备deviceKey	是
sn	String	子设备sn号	是

网关请求云端查询拓扑关系

topic：proxy/structureGet

payload说明：

 {
   "connDeviceKey": "connDeviceKey"
 }

参数说明：

参数	类型	说明	必选	备注
connDeviceKey	String	网关deviceKey	是

网关代理子设备上下线

topic：proxy/structureStatus

payload说明：

 {
   "onlineSns": ["sn1","sn2"],
   "offlineSns": ["sn3","sn4"]
 }

参数说明：

参数	类型	说明	必选	备注
onlineSns	array	网关下子设备上线的sn号集合	否
offlineSns	array	网关下子设备下线的sn号集合	否

云端下发子设备上下线结果

topic：rsp/proxy/notify

payload说明：

{
  "loginSuc": [{"sn":"sn1","deviceKey":"deviceKey1"}],
  "loginFail": [{"code":"1","snSet":["sn2"]}],
  "offlineSuc": [{"childDeviceKey":"childDeviceKey3","reasonCode":"1"}],
  "offlineFail": [{"childDeviceKey":"childDeviceKey4","reasonCode":"0"}]
}

参数说明：

参数	类型	说明	必选	备注
loginSuc	array	登录成功的子设备	否	deviceKey为子设备的deviceKey，网关需对其进行记录，以便子设备的数据上传与命令下发等操作
loginFail	array	登录失败的子设备	否	code为原因码("1"：鉴权不通过，"2"：子设备重复登录)，snSet为登录失败的子设备sn号集合
offlineSuc	array	下线成功的子设备	否	childDeviceKey为子设备deviceKey，reasonCode为原因码("1"：网关请求下线，"2"：子设备被平台强制下线)
offlineFail	array	下线失败的子设备	否	childDeviceKey为子设备deviceKey，reasonCode暂无明确意义

修改设备信息

topic：api/setDeviceInfo

payload说明：

[
   {
       "sn":"sn1",
       "deviceName":"deviceName"
       "descr":"设备描述"
   }
]

参数说明：

参数	类型	说明	必选	备注
sn	String	设备sn号	是
deviceName	String	设备名称	否
descr	String	设备描述	否

说明：
1、普通设备和网关都可以修改设备名称
2、子设备通过网关修改设备名称
3、普通设备修改名称，payload只能传一组信息
部分error：
1、所传sn不存在？
2、网关：所传sn不是该网关下子设备或网关本身
3、普通设备：所传sn不是该普通设备
4、普通设备仅支持传一组数据

物联卡信息维护

topic：api/setCardInfo

payload说明：

[{
 "sn": "16559712022722698958807_1655971244000",
 "msisdn": "1440201296731",
 "iccid": null,
 "imsi": null,
 "operatorName": null
}]

参数说明：

参数	类型	说明	必选	备注
sn	String	设备sn号	是
msisdn	String	物联卡msisdn	是
iccid	String	物联卡iccid	否
imsi	String	物联卡imsi	否
operatorName	String	运营商（移动、联调、电信）	是

网关上传网络拓扑图

topic：api/setparent

payload说明：

 [
   {
    "sn": "sn1", 
    "parent": "sn2"
   }
 ]

参数说明：

参数	类型	说明	必选	备注
sn	String	子设备sn号	是
parent	String	父设备sn号	否	parent为sn对应的子设备的父设备sn号(parent为空时,默认子设备的父设备为当前网关)