固件升级服务

更新时间：2018-10-19 11:29:34

提供一组与OTA固件升级相关的配套服务接口，客户端应用通过本组接口可以获取指定设备的固件信息以及固件升级状态，同时提供了固件升级确认接口（当固件升级需要用户许可时使用）。

获取固件升级信息

定义描述

path 版本 描述 是否需要用户 身份的鉴权
/thing/ota/progress/getByUser 1.0.2 获取某一个设备的固件升级信息，需要指定具体的固件版本号。如果存在相应的固件，返回当前固件的升级进度等信息。 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotId String 是 设备id
version String 是 对应的固件版本号

返回参数

字段名
字段类型
必有
详细描述
iotId
String
是
设备id
step
Integer
是
升级进度（当为负数时，表示升级错误信息，非负数时为升级进度百分比）
升级错误信息定义如下：
-1：升级操作失败
-2：固件文件下载失败
-3：固件文件校验失败
-4：固件文件烧写失败
desc
String
否
描述信息
success
Boolean
是
是否成功标记，当为true时表示固件升级操作成功，反之表示升级未完成（可能正在升级或升级失败），请优先选择upgradeStatus参数来判断固件升级状态
needConfirm
Boolean
是
是否需要用户进行确认操作
upgradeStatus
Integer
是
当前升级状态
0：待升级/待确认
1：升级中
2：升级异常
3：升级失败
4：升级成功

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "",
        "version": "1.0.1"
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200,
    "data": {
        "iotId": "xxxx",
        "step": 10,
        "desc": "xxxxxx",
        "success": false,
        "needConfirm": true,
        "upgradeStatus": 0
    }
}

错误码

错误码 错误信息 来源 描述
9112 there is no device exist 业务 设备不存在
9119 firmware not exist 业务 固件不存在
9146 upgrade record not exist 业务 升级记录不存在

获取设备固件

定义描述

path 版本 描述 是否需要用户 身份的鉴权
/thing/ota/info/queryByUser 1.0.2 获取某一个设备当前的升级固件信息 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotId String 是 设备id

返回参数

字段名
字段类型
必有
详细描述
currentVersion
String
是
当前设备实际烧录的版本号
version
String
是
待升级设备的目标版本号，如果目标版本号比实际烧录固件版本号低，则返回的是当前设备实际烧录的版本号
currentTimestamp
Date
否
设备当前烧录的固件，对应的文件上传到云端时记录的时间
timestamp
Date
是
设备当前最新固件文件上传到云端时记录的时间
size
String
是
文件包大小，单位Byte
md5
String
是
版本固件文件md5
name
String
是
版本固件名称
url
String
是
版本固件地址，sts加密
desc
String
否
版本详情描述

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxx"
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200,
    "data": {
        "currentVersion": "1.2.2",
        "version": "1.2.3",
        "currentTimestamp": "2017-09-08 16:08:08",
        "timestamp": "2017-09-10 12:11:34",
        "size": "4000000",
        "md5": "xxxxxxx",
        "name": "xxxxxxx",
        "url": "xxxxxxx",
        "desc": "xxxxxxx"
    }
}

错误码

错误码 错误信息 来源 描述
9112 there is no device exist 业务 设备不存在
9119 firmware not exist 业务 固件不存在
9132 non-existent job record 业务 升级任务记录不存在

取消固件升级

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/ota/unupgradeByUser 1.0.2 取消某一个设备的固件升级流程 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
version String 是 对应的固件版本号
iotId String 是 设备id

返回参数

字段名
字段类型
必有
详细描述
data
Boolean
是
取消操作指令处理是否成功
True：成功
False：失败

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxxxx",
        "version": "1.0.1"
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200,
    "data": "true"
}

错误码

错误码 错误信息 来源 描述
9112 there is no device exist 业务 设备不存在
9119 firmware not exist 业务 固件不存在
9132 non-existent job record 业务 升级任务记录不存在

触发固件升级

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/ota/upgradeByUser 1.0.2 触发启动某一个设备的固件升级动作(蓝牙设备适用) 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
version String 是 对应的固件版本号
iotId String 是 设备id

返回参数

字段名
字段类型
必有
详细描述
currentVersion
String
是
当前设备实际烧录的版本号
version
String
​
是
待升级设备的目标版本号，如果目标版本号比实际烧录固件版本号低，则返回的是当前设备实际烧录的版本号
​
currentTimestamp
Date
否
设备当前烧录的固件，对应的文件上传到云端时记录的时间
timestamp
Date
是
设备当前最新固件文件上传到云端时记录的时间
size
String
是
文件包大小，单位Byte
md5
String
是
版本固件文件md5
name
String
是
版本固件名称
url
String
是
版本固件地址，sts加密
desc
String
否
版本详情描述

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxxxxx",
        "version": "1.0.1"
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200,
    "data": {
        "currentVersion": "1.2.2",
        "version": "1.2.3",
        "currentTimestamp": "2017-09-08 16:08:08",
        "timestamp": "2017-09-10 12:11:34",
        "size": "4000000",
        "md5": "xxxxxxx",
        "name": "xxxxxxx",
        "url": "xxxxxxx",
        "desc": "xxxxxxx"
    }
}

错误码

错误码 错误信息 来源 描述
9103 update data failed 业务 升级失败
9112 there is no device exist 业务 设备不存在
9132 non-existent job record 业务 升级任务记录不存在

获取正在升级的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/ota/upgrade/listByUser 1.0.2 获取当前正在升级的设备列表信息 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述

返回参数

字段名 字段类型 必有 详细描述
data List 无 当前正在升级的设备信息列表

列表结构

字段名
字段类型
必有
详细描述
iotId
String
是
设备id
step
Integer
是
升级进度（当为负数时，表示升级错误信息，非负数时为升级进度百分比）
升级错误信息定义如下：
-1：升级操作失败
-2：固件文件下载失败
-3：固件文件校验失败
-4：固件文件烧写失败
desc
String
否
描述信息
success
Boolean
是
是否成功标记，当为true时表示固件升级操作成功，反之表示升级未完成（可能正在升级或升级失败），请优先选择upgradeStatus参数来判断固件升级状态
needConfirm
Boolean
是
是否需要用户进行确认操作
upgradeStatus
Integer
是
当前升级状态
0：待升级/待确认
1：升级中
2：升级异常
3：升级失败
4：升级成功

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200,
    "data": [
        {
            "iotId": "xxxx",
            "step": 10,
            "desc": "xxxxxx",
            "success": false,
            "needConfirm": true,
            "upgradeStatus": 0
        },
        {
            "iotId": "xxxx",
            "step": 10,
            "desc": "xxxxxx",
            "success": false,
            "needConfirm": true,
            "upgradeStatus": 0
        }
    ]
}

错误码

错误码 错误信息 来源 描述
9131 invalid device 业务 非法的设备
9144 device count exceeded 业务 设备数量超限

上报固件升级进度

定义描述

path 版本 描述 是否需要用户身份的鉴权
/ota/progress/postByUser 1.0.2 上报某一个设备的固件升级的进度信息给到云端进行记录 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotId String 是 设备id
step String 是 固件升级进度信息（百分比）
desc String 是 升级信息的描述
version String 是 对应的固件版本号信息

返回参数

字段名 字段类型 必有 详细描述

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxx",
        "step": "1",
        "desc": "xxxx",
        "version": "1.0.1"
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200
}

错误码

错误码 错误信息 来源 描述
9112 there is no device exist 业务 设备不存在
9143 upgrade info posted is invalid 业务 升级进度上报错误

上报版本号

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/ota/version/reportByUser 1.0.2 上报某一个设备当前烧录的版本号信息给云端 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotId String 是 设备id
version String 是 固件版本号

返回参数

字段名 字段类型 必有 详细描述

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotId": "xxxx",
        "version": "1.0.1"
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200
}

错误码

错误码 错误信息 来源 描述
9112 there is no device exist 业务 设备不存在
9153 evice auth failed 业务 设备校验失败

批量升级（确认）设备

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/ota/batchUpgradeByUser 1.0.2 批量确认设备进入升级状态，用于需要客户端进行人为确认方可进行升级的场景 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotIds List 是 设备id信息列表

返回参数

字段名 字段类型 必有 详细描述

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
        "iotIds": ["iotid1","iotid2"]
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200
}

错误码

错误码 错误信息 来源 描述
9112 there is no device exist 业务 设备不存在

获取待升级的设备列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/thing/ota/listByUser 1.0.2 获取当前用户名下的待升级（待确认）的设备列表 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述

返回参数

字段名 字段类型 必有 详细描述
data List 无 当前用户名下的待升级（待确认）的设备列表

列表结构

字段名 字段类型 必有 详细描述
iotId String 是 设备id
image String 否 设备对应的品类图标，当云端系统配置了设备所属产品的品类图标时有效
deviceName String 否 设备显示名称，会优先使用用户配置的设备昵称返回，如果不存在昵称的配置则返回对应的产品名称

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.2",
        "iotToken": "token"
    },
    "params": {
    }
}

正常返回示例

{
    "id": "94e0871c-0770-4bb3-9e29-e840d86b3ba6",
    "code": 200,
    "data": [
        {
           "iotId": "xxxx",
           "image": "xxxx",
           "deviceName": "xxxxxx"
        },
        {
           "iotId": "xxxx",
           "image": "xxxx",
           "deviceName": "xxxxxx"
        }
    ]
}

错误码

请参考公共错误码

results matching ""

    No results matching ""