开发设备端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]之间的整数。负数则代表升级失败，具体失败原因如下：
|
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 设置成相应的异常情况描述即可。