2022-07-19

IoT►mqtt

IoT接入文档

4.3 设备与平台通信接口

4.3.1 注册

接口描述：设备上电联网后，检测本地是没有登录信息和注册标志，
设备需要到平台进行注册激活，注册地址固定 URL，且分为测试和正
式服务器地址（域名或 IP、端口）。
正式服务器地址（OPENHOST）：open.clife.cn
测试服务器地址（TESTHOST）：test.clife.cn
正式或者测试服务器请求 URL 只需要对服务器地址进行互换即可。

4.3.1.1 请求

请求 URL：http(s)://OPENHOST/device/register

请求参数：

authLevel=安全认证级别（0 高级，1 中级，2 初级）
productCode=产品编码（初、中级认证级别必选）
devId=设备 ID 号（高级认证级别必选）

请求头：Content-Type: application/json

请求类型：POST

请求方向：设备->平台

参数名	类型	类型	描述
cmd	Number	功能码，取值 2000	Y
ver	String	通讯协议版本，通讯双方需要比对版本号，高版本向下兼容，格式示例：1.0	Y
dir	String	传递方向，同 4.1.1.1	Y
msgId	Number	帧序号，回复帧与请求帧中值相同，否则作为异常处理（丢包、错误）。帧序号由请求方管理，确保帧的唯一性，可做累加计算。	Y
prio	Number	功能优先级，高优先级数据报文优先处理，默认中等优先级。优先级等级： 0：低优先级 1：中优先级 >=2：高优先级	N
timestamp	String	时间戳，最小单位毫秒，UTC-8 时区。设备首次注册使用设备本地时间做时间戳，通过平台回复内容再同步时间戳。	Y
data	Object	关键数据对象体，HTTP 请求时需要对此数据内容作加密并使用 base64 编码处理，加解密密钥需平台申请 devKey	Y
productCode	String	data 中成员，产品编码，平台申请，初、中级认证必选	N

4.3.2.8 文件操作

接口描述：平台通知设备下载文件，或者请求设备上传文件。
该接口主要分为升级、日志调试、收发文件三大功能。

4.3.2.8.1 请求

请求方向：平台->设备

参数名	类型	类型	描述
cmd	Number	功能码，取值 2000	Y
ver	String	通讯协议版本，通讯双方需要比对版本号，高版本向下兼容，格式示例：1.0	Y
dir	String	传递方向，同 4.1.1.1	Y
msgId	Number	帧序号，回复帧与请求帧中值相同，否则作为异常处理（丢包、错误）。帧序号由请求方管理，确保帧的唯一性，可做累加计算。	Y
prio	Number	功能优先级，高优先级数据报文优先处理，默认中等优先级。优先级等级： 0：低优先级 1：中优先级 >=2：高优先级	N
timestamp	String	时间戳，最小单位毫秒，UTC-8 时区。设备首次注册使用设备本地时间做时间戳，通过平台回复内容再同步时间戳。	Y
data	Object	关键数据对象体，HTTP 请求时需要对此数据内容作加密并使用 base64 编码处理，加解密密钥需平台申请 devKey	Y
fileMode	String	data 中成员，文件操作模式，取值： “DOWN”：下载模式 “UP”：上传模式 “QUERY”：查询文件信息（主要是版本号）	Y
productVer	Number	data 中成员，产品版本（总版本号），基础版本从 1 开始，下载模式为升级时必选	N
fileInfo	Array of Object	data 中成员，文件信息列表，包括 Url、软硬件版本等	Y
fileType	String	fileInfo 中成员，文件作用类型，取值： 1. 升级功能 “FIRM”：设备升级固件，下载模式 “SUBFIRM”：子设备（插件）的升级固件，下载模式 “PROFILE”：设备 profile 文件 2. 日志调试 “LOG”：设备日志文件，上传模式（3）文件收发 “PHOTO”：照片文件 “VIDEO”：视频文件 “VOICE”：音频文件 “DATA”：记录数据文件	Y
devNum	Number	fileInfo 内部成员，设备（插件）ID 号，当 “fileType”为“SUBFIRM”时必选	N
software	String	fileInfo 内部成员，软件版本号，fileType 为 “FIRM”、“SUBFIRM”升级固件时必选	N
hardware	String	fileInfo 内部成员，硬件版本号，fileType 为 “FIRM”、“SUBFIRM”升级固件时必选	N
url	String	fileInfo 内部成员，下载或者上传文件的 Url文件地址	Y
md5	String	fileInfo 内部成员，下载文件的 MD5 校验码，16 进制字符串格式，升级必选	N
checkSum	Number	fileInfo 内部成员，下载文件的累加和，升级必选	N
startTime	Number	data 中成员，文件操作相对当前系统时间的开始时间偏移，单位秒，三种情况： <0：当前时间之前的时间点 0：当前时间点 >0：当前时间后的时间点	N
stopTime	Number	data 中成员，文件操作相对当前系统时间的结束时间偏移，单位秒，三种情况： <0：当前时间之前的时间点 0：当前时间点 >0：当前时间后的时间点且满足 fileStopTime >= fileStartTime	N

示例：

文件下载模式：

加密前：


{
    "cmd": 2019,
    "ver": "1.0",
    "dir": "30",
    "timestamp": 1617787651542,
    "msgId": 23454,
    "data": {
        "fileMode": "DOWN",
        "productVer": 2,
        "fileInfo": [
            {
                "fileType": "FIRM",
                "devNum": 0,
                "software": "1.0.2.0",
                "hardware": "02",
                "checkSum": 34458424,
                "md5": "6d348c902ace4d09b6d62ce982dc8ace",
                "url": "http://clife.open.cn/device/ota/esp8266.bin"
            },
            {
                "fileType": "SUBFIRM",
                " devNum": 1,
                "software": "01",
                "hardware": "02",
                "checkSum": 764234235,
                "md5": "6d348c902ace4d09b6d62ce982dc8ace",
                "url": "http://clife.open.cn/device/ota/esp8266_1.bin"
            }
        ],
        "startTime": 0,
        "stopTime": 600
    }
}

文件上传模式：


 {
    "cmd": 2019,
    "ver": "1.0",
    "dir": "30",
    "timestamp": 1617787651542,
    "msgId": 231,
    "data": {
        "fileMode": "UP",
        "fileInfo": [
            {
                "fileType": "PHOTO",
                "url": "http://clife.open.cn/device/storage"
            }
        ],
        "startTime": 0,
        "stopTime": 60
    }
}

4.3.2.8.2 响应

用于升级回复、查询回复（升级后版本主动上报）或者主动升级查询。

请求方向：设备->平台

参数名	类型	类型	描述
cmd	Number	功能码，取值 2000	Y
ver	String	通讯协议版本，通讯双方需要比对版本号，高版本向下兼容，格式示例：1.0	Y
dir	String	传递方向，同 4.1.1.1	Y
msgId	Number	帧序号，回复帧与请求帧中值相同，否则作为异常处理（丢包、错误）。帧序号由请求方管理，确保帧的唯一性，可做累加计算。	Y
prio	Number	功能优先级，高优先级数据报文优先处理，默认中等优先级。优先级等级： 0：低优先级 1：中优先级 >=2：高优先级	N
timestamp	String	时间戳，最小单位毫秒，UTC-8 时区。设备首次注册使用设备本地时间做时间戳，通过平台回复内容再同步时间戳。	Y
data	Object	关键数据对象体，HTTP 请求时需要对此数据内容作加密并使用 base64 编码处理，加解密密钥需平台申请 devKey	Y
respCode	Number	data 中成员，升级结果码，详见表 5.4-1	Y
respCont	String	data 中成员，升级结果描述，详见表 5.4-1	Y
productVer	Number	data 中成员，产品版本（总版本号），基础版本从 1 开始, respCode 为 3 是必选	N
devVer	Array of Object	data 中成员，设备版本，包括软件版本、硬件版本、设备编号, respCode 为 3 是必选	N
software	String	devVer 中成员，设备软件（固件）版本，格式“主版本.次版本.修订版本.修复版本”，如1.0.0.0，详见 5.1	N
hardware	String	devVer 中成员，设备硬件版本，格式“主版本.次版本”，如 1.0	N
devNum	Number	devVer 中成员，设备编号，特别的，0 代表通信模组	N

示例：

文件升级（下载模式）回复：

{
    "cmd": 2018,
    "ver": "1.0",
    "dir": "03",
    "timestamp": 1617787651542,
    "msgId": 23454,
    "data": {
        "respCode": 3,
        "respCont": "ver",
        "productVer": 2,
        "devVer": [
            {
                "software": "1.0.0.0",
                "hardware": "1.0",
                "devNum": 0
            },
            {
                "software": "01",
                "hardware": "02",
                "devNum": 1
            }
        ]
    }
}

主动升级查询：


{
    "cmd": 2018,
    "ver": "1.0",
    "dir": "03",
    "timestamp": 1617787651542,
    "msgId": 23454,
    "data": {
        "respCode": 2,
        "respCont": "SUBFIRM"
    }
}

5.1 版本号约定

格式：主版本.次版本.修订版本.修复版本

版本号变化说明如表 5.1-1：

版本号	软件	硬件
主版本	软件兼容性变化时递增	硬件大改动时递增
次版本	软件增加新功能，不影响兼容性时递增	硬件小改动时递增，非必需
修订版本	BUG 修复时递增	无
修订版本	优化记录或者测试时递增，非必需	无

表 5.1-1 版本号变化说明

版本级别：主版本 > 次版本 > 修订版本 > 修复版本

当低一级别的版本号累计到 100 时，递增上一级版本，低一级版本号归零。

5.3 功能 ID

版本号	说明
2000	注册请求
2001	注册响应
2004	连接请求
2005	连接响应
2006	数据上报请求
2009	数据查询请求
2011	数据控制请求
2012	解绑回复
2013	设备解绑
2014	遗嘱
2017	强制下线
2018	文件操作响应
2019	文件操作请求

表 5.3-1 功能 ID 统计
说明：

功能码在 2000 及以上范围表示设备与服务器使用的功能码；

功能码 2000 以下范围属于本地通信使用，其中 1100 以下范围功能码用作配网，1100 及以上范围用作设备与网关通信使用。

5.4 升级结果码

响应码(respCode)	描述(respCont)	说明
0	[1,100]	升级进度信息: 1:版本下载完成,开始升级 100:升级完成
1	[1,100]	下载进度信息: 1:开始下载 100:完成下载
2	[ALL,FIRM,SUBFIRM]	设备主动请求升级： ALL：设备所有升级固件（默认） FIRM: 设备升级固件新版本请求 SUBFIRM: 子设备（插件）的升级固件新版本请求
3	描述信息	查询响应信息：服务器查询时回复
-1	[0,1,2,X]	过程异常信息： 0:URL非法或设备忙; 1:升级中断; 2:版本下载完成,校验异常取消升级; X:其他异常信息(可为具体描述)

表 5.4-1 升级结果码表

具体为：

      正常升级：{1,1},{1,100},{0,1},{0,100}上报至少 4 个事件

      升级异常：{-1,0};{-1,1};{-1,2}上报三种情况之一的若干事件

      主动（重新）请求升级：{2,FIRM} 或者 {2,SUBFIRM}