平台提供一组OTA固件升级的接口,客户端App通过本组接口可以获取指定设备的固件信息以及固件升级状态,同时提供了固件升级确认接口(当升级需要用户许可时使用)。只有管理员用户才具有调用固件升级接口的权限(设备的被分享者无法调用该设备的固件升级接口,只能查询固件升级的进度)。

获取固件升级信息

定义描述

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-xxxx-xxxx-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-xxxx-xxxx-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-xxxx-xxxx-e840d86b3ba6",
        "code": 200,
        "data": "true"
    }

获取正在升级的设备列表

定义描述

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

请求参数

返回参数

参数 子参数 类型 必有 描述
data JSON Array 当前正在升级的设备信息列表
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-xxxx-xxxx-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-xxxx-xxxx-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-xxxx-xxxx-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-xxxx-xxxx-e840d86b3ba6",
        "code": 200
    }

获取待升级的设备列表

定义描述

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

请求参数

返回参数

参数 子参数 类型 必有 描述
data JSON Array 当前用户名下的待升级或待确认的设备列表
iotId String 设备id
image String 设备对应的品类图标,当云端系统配置了设备所属产品的品类图标时有效
deviceName String 设备显示名称,会优先使用用户配置的设备昵称返回,如果不存在昵称的配置则返回对应的产品名称

示例

  • 请求示例
    {
        "id": "1509086454180",
        "version": "1.0",
        "request": {
            "apiVer": "1.0.2",
            "iotToken": "token"
        },
        "params": {
        }
    }
  • 正常返回示例
    {
        "id": "94e0871c-0770-xxxx-xxxx-e840d86b3ba6",
        "code": 200,
        "data": [
            {
               "iotId": "xxxx",
               "image": "xxxx",
               "deviceName": "xxxxxx"
            },
            {
               "iotId": "xxxx",
               "image": "xxxx",
               "deviceName": "xxxxxx"
            }
        ]
    }