开发设备端 OTA 能力¶

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

设备上报固件版本信息：设备与云端建立连接时，上报当前版本信息，由云端记录版本号。
设备接收云端升级推送请求：接收云端推送的升级请求并下载固件文件。
设备主动请求可升级固件版本：设备可向云端查询并获取可升级的版本信息。
设备上报升级进度及失败原因：在升级过程中，上报进度或失败的错误原因，便于远程管理。

备注

设备 OTA 升级需具备相应物理条件。EnOS 云端提供消息通道和文件下载服务，并通过 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/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.upgrade`
params	Object	必需	固件信息参数
version	String	必需	固件版本号
sign	String	必需	固件签名
signMethod	String	必需	签名算法（如 md5）
fileUrl	String	必需	固件文件下载 URL
fileSize	Long	必需	固件大小（字节）
code	Integer	必需	返回码，200 表示成功

上报固件升级进度¶

设备下载固件后，可通过以下 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.progress`
params	Object	必需	上报进度参数
step	String	必需	升级进度（0-100 表示百分比，负数表示失败，详见下表）
desc	String	可选	进度描述或错误信息
code	Integer	必需	返回码，200 表示成功

Step 失败值说明¶

Step 值	含义
-1	升级固件版本失败
-2	下载固件失败
-3	校验固件失败
-4	烧写固件失败
-5	设备主动忽略

返回码说明¶

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

主动请求升级¶

设备可主动请求获取可升级版本信息。云端若配置了“设备请求升级”策略，将返回可用固件列表，设备或所有者选择升级版本。

上行 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 值	含义
-1	未定义异常
-2	下载失败
-3	校验失败
-4	烧写失败
-5	设备主动忽略

自定义异常¶

若需定义其他异常，可设置 step 为小于 -5 的值，并在 desc 中描述具体情况。