爱星物联协议介绍

**爱星物联平台与设备通讯协议采用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" }} ```