平台提供一组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"
        }
    ]
}