爱星物联协议介绍

显示全部楼层 · 2024-10-25 17:55:19

爱星物联平台与设备通讯协议采用json格式，基础格式如下：

Header : 协议头:

ns : 是命令空间，参考后续定义，不可随意更改，字符串类型。

name: 名称，可以是事件名称，除后续说明的外，可以自定义，建议和属性和事件名称一致，字符串类型。

mid: 消息编号，唯一标识一次交互消息。响应时请回传mid，以便平台标记一次交互，字符串类型。

ts : 时间戳，整型。

ver：版本号。三分节版本号，如1.2.3,两个点分开，字符串类型。

gid: 网关编号，有网关的设备请填写，没有则置空，字符串类型。

from: 消息源头。标识什么渠道发送的本消息，暂定：设备-device; APP-app; Cloud-cloud

Payload: 负载数据:

param: 云端查询参数。

control: 云端控制参数。

device: 设备上报属性。

示例如下：

{
  "header": {
    "ns": "iot.device.control",
    "name": "control",
    "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
    "ts": 1632618621717,
    "ver": "2.0.6.0002",
    "gid": ""
  },
  "payload": {
    "param": {
        //云端查询参数  
    },
    "control": {
        //云端控制参数  
    },
    "device": {
        //设备上报属性 
    }
  }
}

设备配网

配网的时候，无论AP配网还是BLE配网，APP推送的数据区域是一致的，但是使用协议不同协议的结构有所不同，这里我们主要介绍数据区域的内容；

{
  "ssid": "miot_default", 
  "password": "123456789",
  "wificc": "CN",
  "mqttip": "0.0.0.0",
  "mqttport": 1883,
  "tz": "GMT+0800",
  "ts": "165656565",
  "token": "eyJVc2VySUQiOiI2MTA3N"
}

字段名	值类型	说明
ssid	string	路由器SSID名称
password	string	路由密码
wificc	string	国家码
mqttip	string	MQTT地址IP部分
mqttport	int	MQTT地址端口部分
tz	string	时区
ts	int	时间戳
token	string	AES加密后的16进制字符串，详见下述第(2)节。

设备在线上报

设备上电之后会上报设备在线状态，设备断连云端也会触发遗嘱消息上报设备离线状态；

# Topic: {ProductKey}/{DeviceId}/online
# 离线：offline
# 在线：online
{
 "header": {
   "ns": "iot.device.report",
   "name": "online",
   "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
   "ts": 1632618621717,
   "ver": "2.0.6.0002",
   "gid": ""
  },
 "payload": {
   "onlineStatus": "offline/online"
  }
  }

获取设备信息

平台、App可通过info主题请求获取设备信息

# 发布查询设备信息
# topic: {ProductKey}/{DeviceId}/info
{
  "header": {
    "ns": "iot.device.info",
    "name": "info",
    "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
    "ts": 1632618621717,
    "ver": "2.0.6.0002",
    "gid": ""
  }
}
# 订阅主题获取设备信息，如果消息内容中有token，则表示配网激活的消息
# topic: {ProductKey}/{DeviceId}/info/report
{
  "header": {},
  "payload": {
    "code": 0,
    "uid": 2186359217,
    "deviceId": "xxx",
    "productKey": "xxxxx",
    "token": "226a518d2d972b221e9c23a7eb0535f4",
    "secrtKey": "局域网通讯密钥",
    "fwVer": "2.0.6",
    "mcuVer": "2.0.6",
    "hwVer": "esp32",
    "memFree": 66304,
    "mac": "40:31:3C:3F:A8:59",
    "ap": {
      "ssid": "zifeng",
      "bssid": "EC:41:18:4F:FE:D5",
      "rssi": -22,
      "primary": 2
    },
    "netif": {
      "localIp": "192.168.31.44",
      "mask": "255.255.255.0",
      "gw": "192.168.31.1"
    }
  }
}

payload 说明:

productKey	产品Key
token	配网token，如果上报了token，则表示设备激活
secrtKey	局域网通讯密钥
fwVer	通讯固件版本号
mcuVer	MCU固件版本号
hwVer	硬件版本号
memFree	剩余内存
mac	设备MAC地址
ap	wifi相关信息，比较关键的rssi，为信号强度
netif	网络相关信息，localIp为局域网IP

App/云端查询属性

如果平台或者APP想要主动查询设备的属性，则可以通过以下协议获取

topic: {ProductKey}/{DeviceId}/query
{
 "header": {
   "ns": "iot.device.query",
   "name": "query",
   "mid": "1bd5d003-31b9-476f",
   "ts": "1632618621717",
   "ver": 1
  },
 "payload": {
   "param": [
     "1",
     "2",
     "3",
     "4"
    ]
  }}

# 设备收到消息，上报请求的属性数据
topic: {ProductKey}/{DeviceId}/report
{
  "header": {
    "ns":"iot.device.query",
    "name": "query",
    "mid":"1bd5d003-31b9-476f",
    "ts": "1632618621717",
    "ver": 1
  },
  "payload": {
    "code": 0,
    "device": {
      "1": true,
      "2": 20,
      "3": 1,
      "4": false
    }
  }}

属性功能控制

如果App或者平台想要直接控制设备的某个功能，使用control主题相关协议触发；

topic: {ProductKey}/{DeviceId}/control
{
 "header": {
   "ns": "iot.device.control",
   "name": "control",
   "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
   "ts": 1632618621717,
   "ver": "2.0.6.0002",
   "gid": ""
  },
 "payload": {
   "control": {
     "1": true
    }
  }}

# 设备收到控制功能消息，将回复ack
topic: {ProductKey}/{DeviceId}/control/ack
{
 "header": {
   "ns": "iot.device.control",
   "name": "control",
   "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
   "ts": 1632618621717,
   "ver": "2.0.6.0002",
   "gid": ""
  },
 "payload": {
   "code": 0
  }
}

# 当设备属性变更成功之后，将上报状态变化数据
topic: {ProductKey}/{DeviceId}/report
{
 "header": {
   "ns": "iot.device.query",
   "name": "query",
   "mid": "1bd5d003-31b9-476f",
   "ts": "1632618621717",
   "ver": 1
  },
 "payload": {
   "code": 0,
   "device": {
     "1": true
    }
  }}

恢复出厂

用户移除设备，需要主动给设备发送设备恢复出厂消息，帮助清理使用痕迹、开启配网热点等

topic: {ProductKey}/{DeviceId}/control
{
  "header": {
    "ns": "iot.device.control",
    "name": "restore",
    "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
    "ts": 1632618621717,
    "ver": "2.0.6.0002",
    "gid": ""
  }
}
topic: {ProductKey}/{DeviceId}/control/ack
{
  "header": {...},
  "payload": {
    "code": 0
  }
}

UTC时间同步

设备上电之后会主动发起同步UTC时间请求，平台收到请求下发同步UTC时间；

topic: {ProductKey}/{DeviceId}/utc
{
  "header": {
    "ns": "iot.device.utc",
    "name": "utc",
    "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
    "ts": 1632618621717,
    "ver": "2.0.6",
    "gid": ""
  }
}

#设备接收服务响应数据，同步更新UTC时间
{
  "header": {...},
  "payload": {
    "code": 0,
    "data": "2006-01-02T15:04:05Z"
  }
}

OTA

如果需要给设备升级固件，这里需要用到ota相关主题的协议；

升级下发 payload.param 说明

chanel	升级渠道（1-云端、2-APP）
pointVer	指定目标版本
baseVer	固件最低兼容版本
mcuBaseVer	mcu最低兼容版本
otaType	module_ota_all / module_mcu_all
appUrl	oss永久有效的外链地址
md5	当前待升级的固件包文件的MD5值
pubId	发布编号（升级结果需要回传）
otaVer	OTA当前升级版本（升级结果需要回传）
timeout	升级超时时间

升级结果进度上报说明

属性	描述
otaState	该字段表示OTA的状态<br />Downloading:下载中<br />Installing:安装中安装完成之后，本字段不传。
code	升级结果状态编码<br />0：表示OTA成功<br />1：表示下载失败<br />2：表示安装失败<br />3：协议数据错误<br />4：OTA数据包错误<br />5:设备处理失败<br />6：OTA版本号错<br />7：OTA功能已启动
pubId	发布编号（升级结果需要回传）
otaVer	OTA当前升级版本（升级结果需要回传）

# App用户主动下发OTA升级消息；
{
   "header":{
       "ns":"iot.device.upgrade",
       "name":"otaInfo",
       "mid":"1bd5d003-31b9-476f-ad03-71d471922820",
       "ts":1632618621717,
        "ver":"2.0.6.0002",
       "gid":""
   },
   "payload":{
       "param":{
           "chanel":1,
           "pointVer":"1.1.0",
           "baseVer":"1.1.0",
           "mcuBaseVer":"1.0.0",
           "otaType":"module_ota_all",
           "otakey":"当前升级固件key",//通过固件Key区分具体需要升级的扩展固件，考虑多个扩展固件的情况
           "appUrl":"https://xxx.com/xxx_app.bin",
           "md5":"12312312312312",
           "pubId": "发布Id",
           "otaVer": "1.0.1"
       }
    }
}
# 设备收到升级通知
topic: {ProductKey}/{DeviceId}/upgrade/ack
{
 "header": {
   "ns": "iot.device.upgrade",
   "name": "otaInfo",
   "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
   "ts": 1632618621717,
   "ver": "2.0.6.0002",
   "gid": ""
  },
 "payload": {
   "code": 0
  }
}
# 设备上报升级进度和结果；
# 根据otaState、code判断升级结果，根据pubId更新升级记录结果；
{
 "header": {
   "ns": "iot.device.upgrade",
   "name": "otaProgress",
   "mid": "1bd5d003-31b9-476f-ad03-71d471922820",
   "ts": 1632618621717,
   "ver": "2.0.6.0002",
   "gid": ""
  },
 "payload": {
   "otaState": "installing",
   "code": -33001,
   "progress": 80,
   "pubId": "OTA发布编号",
   "otaVer": "1.0.1"
  }}