开发设备端OTA能力¶

设备端OTA升级很大程度上依赖于设备自身的物理空间和功能实现。针对硬件开发者，EnOS平台提供包含OTA能力的Device SDK，支持以下功能：

设备上报固件版本信息：设备与云端建连时上报一次自身的版本信息，云端记录设备的版本号；
设备接收云端升级推送请求：云端推送升级请求后，设备可接收到升级请求并下载固件文件；
设备向云端主动请求可升级的固件版本：支持设备主动向云端请求，并查询可升级的版本信息；
设备上报升级进度和升级失败的错误原因：设备进入升级流程后，可向云端上报升级的进度或升级失败的原因，方便运维人员进行远程升级管理；

备注

一般而言，设备的OTA升级需要具备相应的物理条件，EnOS平台提供设备OTA升级所需的云端消息通道和文件下载服务，并提供设备端SDK方便开发者调用接口能力，而真正的设备端固件升级则依赖于设备端Flash是否具备足够的物理空间，开发者需自行实现文件下载后的固件切换、引导和重启等业务逻辑。

安装Device SDK¶

升级请求支持使用MQTT进行消息的发送和订阅，和使用HTTP进行消息的推送和获取。有关各个步骤和示例代码，参阅以下内容。

固件升级协议¶

设备端上报版本号¶

设备端可发送当前的固件版本号给云端，只有上报过固件版本号的设备，才能在控制台创建升级任务。设备与云端每次建连成功后，设备将通过此topic/端点上报当前的版本号信息。

上行Topic/信息:

请求: /sys/${productkey}/${devicekey}/ota/device/inform
响应: /sys/${productkey}/${devicekey}/ota/device/inform_reply

请求数据格式：

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.inform",
    "params": {
        "version":"xxxxxxxx"
    }
}

响应数据格式：

{
    "id": "123",
    "code": 200,
    "data": {}
}

参数说明：

参数	类型	是否必须	描述
id	Long	可选	消息ID，保留值
version	String	必需	协议版本号，目前协议版本1.0
method	String	必需	请求方法，必需为ota.device.inform
params	Object	必需	上报版本号参数
version	String	必需	上报的版本号
code	Integer	必需	结果返回码，200代表请求成功执行

设备接收云端请求¶

在控制台创建云端推送的固件升级任务，符合升级条件的在线设备，将会收到云端推送过来包含固件名称、版本号、MD5和下载URL等固件信息，如果当前设备不在线，将在下次上线时接收到升级请求。

下行Topic (MQTT)：

请求：/sys/${productkey}/${devicekey}/ota/device/upgrade
响应：/sys/${productkey}/${devicekey}/ota/device/upgrade_reply

下行信息 (HTTP)：

云端有OTA命令时，升级命令包含在设备登录或上传测点的云端响应中。

请求command-payload：/ota/device/upgrade

请求数据格式：

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.upgrade",
    "params": {
        "version":"v1.0",
        "sign":"xxxxxxx",
        "signMethod":"md5",
        "fileUrl":"/1b30e0ea83002000/ota/kadak13",
        "fileSize":1024
    }
}

响应数据格式：

{
    "id": "123",
    "code": 200,
    "data": {}
}

参数说明：

参数	类型	是否必须	描述
id	Long	可选	消息ID，保留值
version	String	必需	协议版本号，目前协议版本1.0
method	String	必需	请求方法，必需为ota.device.getversion
params	Object	可选	无
code	Integer	必需	结果返回码，200代表请求执行成功
data	List	可选	返回的详细信息，JSON格式
version	String	必需	固件版本号
sign	String	必需	固件签名
signMethod	String	必需	固件签名算法
fileUrl	String	必需	固件文件url
fileSize	Long	必需	固件文件大小，单位：字节

设备上报固件升级进度¶

设备开始下载固件后，可以通过此topic/信息上报升级进度，或上报升级错误的相关原因。运维人员可以在控制台中查看升级进度。

上行Topic/信息：

请求：/sys/${productkey}/${devicekey}/ota/device/progress
响应：/sys/${productkey}/${devicekey}/ota/device/progress_reply

请求数据格式：

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.progress",
    "params": {
        "step":"1",
        "desc":"xxxxxxxx"
    }
}

响应数据格式：

{
    "id": "123",
    "code": 200,
    "data": {}
}

参数说明：

参数	类型	是否必须	描述
id	Long	可选	消息ID，保留值
version	String	必需	协议版本号，目前协议版本1.0
method	String	必需	请求方法，必需为ota.device.process
params	Object	必需	上报进度参数
step	String	必需	上报的进度，固件升级进度比，正常范围为[0, 100]之间的整数。负数则代表升级失败，具体失败原因如下： -1：升级固件版本失败 -2：下载固件失败 -3：校验固件失败 -4：烧写固件失败 -5：设备主动忽略固件
desc	String	可选	当前步骤的描述信息，如果发生异常可以用此字段承载错误信息
code	Integer	必需	结果返回码，200代表请求成功执行

返回码	错误信息	释义
764	Device task not found	没有找到与该设备相关的ota升级任务
765	Device task not start	设备尚未启动ota升级任务

设备主动请求升级¶

设备可以主动请求，以获取可升级的版本信息。云端将创建一个OTA升级策略为“设备请求升级”，设备可发布升级请求，接收云端返回的可用的升级版本信息。如果云端存在多个版本信息，则返回一个可升级版本的list，由设备或设备所有者选择进行升级。

上行Topic/信息

请求: /sys/${productkey}/${devicekey}/ota/device/getversion
响应: /sys/${productkey}/${devicekey}/ota/device/getversion_reply

请求数据格式

{
    "id":"123",
    "version":"1.0",
    "method":"ota.device.getversion",
    "params": {
    }
}

响应数据格式：

{
    "id":"123",
    "code":200,
    "data": [
         {
            "version":"v1.0",
            "sign":"xxxxxxx",
            "signMethod":"md5",
            "fileUrl":"/1b30e0ea83002000/ota/kadak13",
            "fileSize":1024
        }
    ]
}

参数说明：

参数	类型	是否必须	描述
id	Long	可选	消息ID，保留值
version	String	必需	协议版本号，目前协议版本1.0
method	String	必需	请求方法，必需为ota.device.getversion
params	Object	可选	无
code	Integer	必需	结果返回码，200代表请求成功执行
data	List	可选	返回的详细信息，JSON格式，如果该设备在云端存在多个可升级的版本，将返回多版本信息
version	String	必需	固件版本号
sign	String	必需	固件签名
signMethod	String	必需	固件签名算法
fileUrl	String	必需	固件文件url
fileSize	Long	必需	固件文件大小，单位：字节

异常情况处理¶

对于固件升级过程的异常情况，可以在上报固件升级进度时，通过参数step和desc来表示异常情况。step 小于 0，表示异常情况，desc 则是对异常情况的描述。

目前系统提供的异常情况 step 如下：

step值	含义
-1	未定义异常
-2	下载失败
-3	校验失败
-4	烧写失败
-5	设备主动忽略

若有其它自定义异常，可设置 step 为小于 -5 的数字，desc 设置成相应的异常情况描述即可。