设备 OTA 升级

更新时间：2025-04-25 08:08:45下载pdf

您可以使用以下 API 查询您的设备信息。

请求方式	API	描述
GET	/v1.0/cloud/illume/devices/device/ota/open/detail	获取设备 OTA 详情
POST	/v1.0/cloud/illume/devices/ota/open/upgrade	升级设备 OTA
GET	/v1.0/cloud/illume/devices/ota/open/tobeupgraded	获取设备 OTA - 待升级列表
GET	/v1.0/cloud/illume/devices/ota/open/upgrading	获取设备 OTA - 升级中列表
GET	/v1.0/cloud/illume/devices/ota/open/upgrade/record	获取设备 OTA - 升级完成记录列表
GET	/v1.0/cloud/illume/devices/ota/tobeupgraded/roomid	同步房空间下待升级设备

获取设备 OTA 详情

功能描述

获取设备 OTA 详情。

接口地址

GET /v1.0/cloud/illume/devices/device/ota/open/detail

请求参数

参数名	字段类型	参数类型	说明	是否必需
device_id	String	body	设备 ID	true

返回参数

参数名	字段类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功： `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	unkown	返回结果

Result 参数说明

{
    "result": {
        "current_version": "String//当前固件版本",
        "device": {
            "active_time": "Long//设备活跃时间",
            "category": "String//产品所属二级分类",
            "category_code": "String//产品所属三级分类",
            "current_brightness": "Integer//设备所属房间的亮度阈值",
            "device_id": "String//设备 ID",
            "device_mac": "142d41fffe9449c6",
            "device_name": "String//设备名称",
            "device_power": "Double//设备功率",
            "device_saas_id": "String//设备商照唯一 ID",
            "device_status": "String//设备状态",
            "device_type": "String//设备类型",
            "device_type_value": "Integer//设备类型",
            "install_time": "Long//设备安装时间",
            "online": "Boolean//在线状态",
            "owner_id": "String//所属设备家庭组 ID",
            "point_id": "String//设备所在点位 ID",
            "product_id": "String//产品 ID",
            "room_id": "String//空间 ID",
            "top_category": "String//产品所属大级分类",
            "uuid": "String//设备 UUID"
        },
        "device_ext": {
            "device_mac": "String//设备 MAC 地址",
            "firmware_version": "String//固件版本号",
            "gateway_id": "String//设备绑定的网关信息",
            "gateway_name": "String//设备绑定的网关信息",
            "mcu_version": "String//MCU 版本号"
        },
        "device_id": "String//设备 ID",
        "device_saas_id": "String//设备商照唯一 ID",
        "upgrade_status": "Integer//升级状态"
    },
    "success": true,
    "t": 1745492684891,
    "tid": "edcf2eac20fb11f0942fe62c0c16c951"
}

请求示例

{
    "device_id": "tring//设备 ID"
}

响应示例

{
    "result": {
        "current_version": "String//当前固件版本",
        "device": {
            "active_time": "Long//设备活跃时间",
            "category": "String//产品所属二级分类",
            "category_code": "String//产品所属三级分类",
            "current_brightness": "Integer//设备所属房间的亮度阈值",
            "device_id": "String//设备 ID",
            "device_mac": "String//设备 MAC",
            "device_name": "String//设备名称",
            "device_power": "Double//设备功率",
            "device_saas_id": "String//设备商照唯一 ID",
            "device_status": "String//设备状态",
            "device_type": "String//设备类型",
            "device_type_value": "Integer//设备类型",
            "install_time": "Long//设备安装时间",
            "online": "Boolean//在线状态",
            "owner_id": "String//所属设备家庭组 ID",
            "point_id": "String//设备所在点位 ID",
            "product_id": "String//产品 ID",
            "room_id": "String//空间 ID",
            "top_category": "String//产品所属大级分类",
            "uuid": "String//设备 UUID"
        },
        "device_ext": {
            "device_mac": "String//设备 MAC 地址",
            "firmware_version": "String//固件版本号",
            "gateway_id": "String//设备绑定的网关信息",
            "gateway_name": "String//设备绑定的网关信息",
            "mcu_version": "String//MCU 版本号"
        },
        "device_id": "String//设备 ID",
        "device_saas_id": "String//设备商照唯一 ID",
        "upgrade_status": "Integer//升级状态"
    },
    "success": true,
    "t": 1745492684891,
    "tid": "edcf2eac20fb11f0942fe62c0c16c951"
}

升级设备 OTA

功能描述

升级设备 OTA。

接口地址

POST /v1.0/cloud/illume/devices/ota/open/upgrade

请求参数

参数名	字段类型	参数类型	说明	是否必需
project_id	String	body	项目 ID	是
device_ids	String[]	body	设备 IDS	是

返回参数

参数名	字段类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功： `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	Boolean	返回结果

Result 参数说明

{
	"success":true,
	"t":1573441137,
	"result":false
}

请求示例

{
	"project_id":"String//项目 ID",
	"device_ids":[
		"String[]//设备 IDS"
	]
}

响应示例

{
	"success":true,
	"t":1573441137,
	"result":false
}

获取设备 OTA - 待升级列表

功能描述

获取设备 OTA - 待升级列表。

接口地址

GET /v1.0/cloud/illume/devices/ota/open/tobeupgraded

请求参数

参数名	字段类型	参数类型	说明	是否必需
page	int	body	页数，最小为 1	是
page_size	int	body	数量，最大为 100	是
project_id	String	body	项目 ID	是
device_status	String[]	body	设备状态 Expiring Exception Online Offline	否
device_types	int[]	body	设备类型 -1：其他 0：智能灯 1：网关设备 2：非智能灯 3：开关设备 4：传感器设备	否
top_categories	String[]	body	设备状态筛选列表 Code 电工：dgzm 照明：zm 小家电：xjd 安防传感类：jjaf 网关中控：wgzk 其他类：qt	否
room_id	String	body	房间 ID	否
device_name	String	body	设备名称	否
online	Boolean	body	在线状态 false：离线 true：在线	否
upgrade_status	int[]	body	升级状态 0：不可升级 1：可升级 2：升级中 3：升级成功 4：升级失败 5：等待升级	否

返回参数

参数名	字段类型	说明
code	Integer	响应码，详情见错误码章节，成功时为空
success	Boolean	是否成功： `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	unkown	返回结果

result参数说明

{
    "result": {
        "list": [
            {
                "custom_capability": "String//自定义协议类型：Wi-Fi、Zigbee、Sigmesh",
                "device_id": "String//设备 ID",
                "device_name": "String//设备名称",
                "device_saas_id": "String//设备商照唯一 ID",
                "group_type":"List<Integer>//设备协议类型，1：Wi-Fi、2：Zigbee、3：Sigmesh",
                "online": "Boolean//在线状态，false：离线、true：在线",
                "room_name": "String//房间名称",
                "top_category": "String//产品所属大级分类",
                "top_category_name": "String//产品所属大级分类",
                "upgrade_status": "Integer//升级状态，0：不可升级、1：可升级、2：升级中、3：升级成功、4：升级失败、5：等待升级",
                "version": "String//可用固件版本"
            } 
        ],
        "total": "Integer//总数"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

请求示例


{
    "project_id":"String//项目 ID",
    "room_id":"String//房间 ID",
    "page":1,
    "page_size":10
}

响应示例

{
    "result": {
        "list": [
            {
                "custom_capability": "String//自定义协议类型：Wi-Fi、Zigbee、Sigmesh",
                "device_id": "String//设备 ID",
                "device_name": "String//设备名称",
                "device_saas_id": "String//设备商照唯一 ID",
                "group_type":"List<Integer>//设备协议类型，1：Wi-Fi、2：Zigbee、3：Sigmesh",
                "online": "Boolean//在线状态，false：离线、true：在线",
                "room_name": "String//房间名称",
                "top_category": "String//产品所属大级分类",
                "top_category_name": "String//产品所属大级分类",
                "upgrade_status": "Integer//升级状态，0：不可升级、1：可升级、2：升级中、3：升级成功、4：升级失败、5：等待升级",
                "version": "String//可用固件版本"
            } 
        ],
        "total": "Integer//总数"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

获取设备 OTA - 升级中列表

功能描述

获取设备 OTA - 升级中列表。

接口地址

GET /v1.0/cloud/illume/devices/ota/open/upgrading

请求参数

参数名	字段类型	参数类型	说明	是否必需
page	int	body	页数，最小为 1	是
page_size	int	body	数量，最大为 100	是
project_id	String	body	项目 ID	是
device_status	String[]	body	设备状态 Expiring Exception Online Offline	否
device_types	int[]	body	设备类型 -1：其他 0：智能灯 1：网关设备 2：非智能灯 3：开关设备 4：传感器设备	否
top_categories	String[]	body	设备状态筛选列表 Code 电工：dgzm 照明：zm 小家电：xjd 安防传感类：jjaf 网关中控：wgzk 其他类：qt	否
room_id	String	body	房间 ID	否
device_name	String	body	设备名称	否
online	Boolean	body	在线状态 false：离线 true：在线	否
upgrade_status	int[]	body	升级状态 0：不可升级 1：可升级 2：升级中 3：升级成功 4：升级失败 5：等待升级	否

返回参数

参数名	字段类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功， `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	unkown	返回结果

result参数说明

{
    "result": {
        "list": [
            {
                "custom_capability": "String//自定义协议类型，Wi-Fi、Zigbee、Sigmesh",
                "device_id": "String//设备 ID",
                "device_name": "String//设备名称",
                "device_saas_id": "String//设备商照唯一 ID",
                "group_type":"List<Integer>//设备协议类型，1：Wi-Fi、2：Zigbee、3：Sigmesh",
                "online": "Boolean//在线状态：false：离线、true：在线",
                "room_name": "String//房间名称",
                "top_category": "String//产品所属大级分类",
                "top_category_name": "String//产品所属大级分类",
                "upgrade_status": "Integer//升级状态，0：不可升级、1：可升级、2：升级中、3：升级成功、4：升级失败、5：等待升级",
                "version": "String//可用固件版本"
            } 
        ],
        "total": "Integer//总数"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

请求示例


{
    "project_id":"String//项目 ID",
    "room_id":"String//房间 ID",
    "page":1,
    "page_size":10
}

响应示例

{
    "result": {
        "list": [
            {
                "custom_capability": "String//自定义协议类型：Wi-Fi、Zigbee、Sigmesh",
                "device_id": "String//设备 ID",
                "device_name": "String//设备名称",
                "device_saas_id": "String//设备商照唯一 ID",
                "group_type":"List<Integer>//设备协议类型，1：Wi-Fi、2：Zigbee、3：Sigmesh",
                "online": "Boolean//在线状态：false：离线、true：在线",
                "room_name": "String//房间名称",
                "top_category": "String//产品所属大级分类",
                "top_category_name": "String//产品所属大级分类",
                "upgrade_status": "Integer//升级状态，0：不可升级、1：可升级、2：升级中、3：升级成功、4：升级失败、5：等待升级",
                "version": "String//可用固件版本"
            } 
        ],
        "total": "Integer//总数"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

获取设备 OTA - 升级完成记录列表

功能描述

获取设备 OTA - 升级完成记录列表。

接口地址

GET /v1.0/cloud/illume/devices/ota/open/upgrade/record

请求参数

参数名	字段类型	参数类型	说明	是否必需
page	int	body	页数，最小为 1	是
page_size	int	body	数量，最大为 100	是
project_id	String	body	项目 ID	是
device_status	String[]	body	设备状态 Expiring Exception Online Offline	否
device_types	int[]	body	设备类型 -1：其他 0：智能灯 1：网关设备 2：非智能灯 3：开关设备 4：传感器设备	否
top_categories	String[]	body	设备状态筛选列表 Code 电工：dgzm 照明：zm 小家电：xjd 安防传感类：jjaf 网关中控：wgzk 其他类：qt	否
room_id	String	body	房间 ID	否
device_name	String	body	设备名称	否
online	Boolean	body	在线状态 false：离线 true：在线	否
upgrade_status	int[]	body	升级状态 0：不可升级 1：可升级 2：升级中 3：升级成功 4：升级失败 5：等待升级	否

返回参数

参数名	类型	说明
code	Integer	响应码（详情见错误码章节），成功时为空
success	Boolean	是否成功： `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	unkown	返回结果

Result 参数说明

{
    "result": {
        "list": [
            {
                "custom_capability": "String//自定义协议类型：Wi-Fi、Zigbee、Sigmesh",
                "device_id": "String//设备 ID",
                "device_name": "String//设备名称",
                "device_saas_id": "String//设备商照唯一 ID",
                "group_type":"List<Integer>//设备协议类型，1：Wi-Fi、2：Zigbee、3：Sigmesh",
                "online": "Boolean//在线状态：false：离线、true：在线",
                "room_name": "String//房间名称",
                "top_category": "String//产品所属大级分类",
                "top_category_name": "String//产品所属大级分类",
                "upgrade_status": "Integer//升级状态，0：不可升级、1：可升级、2：升级中、3：升级成功、4：升级失败、5：等待升级",
                "version": "String//可用固件版本"
            } 
        ],
        "total": "Integer//总数"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

请求示例


{
    "project_id":"String//项目 ID",
    "room_id":"String//房间 ID",
    "page":1,
    "page_size":10
}

响应示例

{
    "result": {
        "list": [
            {
                "custom_capability": "String//自定义协议类型：Wi-Fi、Zigbee、Sigmesh",
                "device_id": "String//设备 ID",
                "device_name": "String//设备名称",
                "device_saas_id": "String//设备商照唯一ID",
                "group_type":"List<Integer>//设备协议类型，1：Wi-Fi、2：Zigbee、3：Sigmesh ",
                "online": "Boolean//在线状态：fals：离线，true：在线",
                "room_name": "String//房间名称",
                "top_category": "String//产品所属大级分类",
                "top_category_name": "String//产品所属大级分类",
                "upgrade_status": "Integer//升级状态，0：不可升级、1：可升级、2：升级中、3：升级成功、4：升级失败、5：等待升级",
                "version": "String//可用固件版本"
            } 
        ],
        "total": "Integer//总数"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

同步房空间下待升级设备

功能描述

同步房空间下待升级设备。

接口地址

GET /v1.0/cloud/illume/devices/ota/tobeupgraded/roomid

请求参数

参数名	字段类型	参数类型	说明	是否必需
project_id	String	body	项目 ID	是
room_id	String	body	空间 ID	是

返回参数

参数名	字段类型	说明
code	Integer	响应码（详情见错误码），成功时为空
success	Boolean	是否成功： `true`：成功 `false`：失败
msg	String	请求失败的信息，成功时为空
t	Long	返回时间戳，13 位
result	unkown	返回结果

Result 参数说明

请求示例

{
    "project_id":"1451224591564378112",
    "room_id":"234761634"
}

响应示例

{
	"success":true,
	"t":1573441137
}

错误码

以下为该接口常见的业务异常。了解更多异常错误，请参考全局错误码。

错误码	说明
500	系统错误

上一篇自定义群组管理

下一篇智能规则