提供一组与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
        }
    }
                

获取设备固件

定义描述

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"
        }
    }
                

取消固件升级

定义描述

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"
    }
                

获取正在升级的设备列表

定义描述

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
            }
        ]
    }
                

上报固件升级进度

定义描述

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
    }
                

上报版本号

定义描述

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
    }
                

批量确认设备升级

定义描述

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
    }
                

获取待升级的设备列表

定义描述

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"
            }
        ]
    }