Device OTA Update

This topic describes how to call the following API operations to query information about your devices.

Request method	APIs	Description
GET	/v1.0/cloud/illume/devices/device/ota/open/detail	Get OTA update details
POST	/v1.0/cloud/illume/devices/ota/open/upgrade	Update the device over the air (OTA)
GET	/v1.0/cloud/illume/devices/ota/open/tobeupgraded	Get the list of devices to be updated via OTA
GET	/v1.0/cloud/illume/devices/ota/open/upgrading	Get the list of devices being updated via OTA
GET	/v1.0/cloud/illume/devices/ota/open/upgrade/record	Get the list of devices updated via OTA
GET	/v1.0/cloud/illume/devices/ota/tobeupgraded/roomid	Sync devices to be updated in the space

Get OTA update details

Functional description

Based on the device ID, get the details of OTA updates for the specified device.

API endpoint

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

Request parameters

Parameter	Field type	Parameter type	Description	Required
device_id	String	body	The device ID.	true

Response parameters

Parameter	Field type	Description
code	Integer	The error code on failure. The value is empty on success.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	unknown	The returned result.

Description of result

{
    "result": {
        "current_version": "String// The current version of the firmware",
        "device": {
            "active_time": "Long // The active time of a device",
            "category": "String // The level-2 category of a product",
            "category_code": "String // The level-3 category of a product",
            "current_brightness": "Integer // The brightness threshold of the space to which a device belongs",
            "device_id": "String // The device ID",
            "device_mac": "String // The MAC address of a device",
            "device_name": "String // The device name",
            "device_power": "Double // The device power",
            "device_saas_id": "String // The unique ID of a commercial lighting device",
            "device_status": "String // The device status",
            "device_type": "String // The device type",
            "device_type_value": "Integer // The value of a device type",
            "install_time": "Long // The installation time of a device",
            "online": "Boolean // Indicates whether a device is online",
            "owner_id": "String // The ID of the home group to which a device belongs",
            "point_id": "String // The ID of the location where a device is deployed",
            "product_id": "String // The product ID",
            "room_id": "String // The space ID",
            "top_category": "String // The top category to which the product belongs",
            "uuid": "String // The universally unique identifier (UUID) of a device",
        },
        "device_ext": {
            "device_mac": "String // The MAC address of a device",
            "firmware_version": "String // The version of the firmware",
            "gateway_id": "String // The ID of the gateway bound with the device",
            "gateway_name": "String // The name of the gateway bound with the device",
            "mcu_version": "String// The version of the MCU"
        },
        "device_id": "String // The device ID",
        "device_saas_id": "String // The unique ID of a commercial lighting device",
        "upgrade_status": "Integer // The update status"
    },
    "success": true,
    "t": 1745492684891,
    "tid": "edcf2eac20fb11f0942fe62c0c16c951"
}

Sample request

{
    "device_id": "String // The device ID",
}

Sample response

{
    "result": {
        "current_version": "String// The current version of the firmware",
        "device": {
            "active_time": "Long // The active time of a device",
            "category": "String // The level-2 category of a product",
            "category_code": "String // The level-3 category of a product",
            "current_brightness": "Integer // The brightness threshold of the space to which a device belongs",
            "device_id": "String // The device ID",
            "device_mac": "String // The MAC address of a device",
            "device_name": "String // The device name",
            "device_power": "Double // The device power",
            "device_saas_id": "String // The unique ID of a commercial lighting device",
            "device_status": "String // The device status",
            "device_type": "String // The device type",
            "device_type_value": "Integer // The value of a device type",
            "install_time": "Long // The installation time of a device",
            "online": "Boolean // Indicates whether a device is online",
            "owner_id": "String // The ID of the home group to which a device belongs",
            "point_id": "String // The ID of the location where a device is deployed",
            "product_id": "String // The product ID",
            "room_id": "String // The space ID",
            "top_category": "String // The top category to which the product belongs",
            "uuid": "String // The universally unique identifier (UUID) of a device",
        },
        "device_ext": {
            "device_mac": "String // The MAC address of a device",
            "firmware_version": "String // The version of the firmware",
            "gateway_id": "String // The ID of the gateway bound with the device",
            "gateway_name": "String // The name of the gateway bound with the device",
            "mcu_version": "String// The version of the MCU"
        },
        "device_id": "String // The device ID",
        "device_saas_id": "String // The unique ID of a commercial lighting device",
        "upgrade_status": "Integer // The update status"
    },
    "success": true,
    "t": 1745492684891,
    "tid": "edcf2eac20fb11f0942fe62c0c16c951"
}

Update the device over the air (OTA)

Functional description

Update the specified device over the air (OTA).

API endpoint

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

Request parameters

Parameter	Field type	Parameter type	Description	Required
project_id	String	body	The project ID.	Yes
device_ids	String[]	body	The device IDs.	Yes

Response parameters

Parameter	Field type	Description
code	Integer	The error code on failure. The value is empty on success.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Boolean	The returned result.

Description of result

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

Sample request

{
  "project_id": "String // The project ID",
  "device_ids":[
    "String[]//The list of device IDs"
  ]
}

Sample response

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

Get the list of devices to be updated via OTA

Functional description

Get the list of devices to be updated via OTA.

API endpoint

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

Request parameters

Parameter	Field type	Parameter type	Description	Required
page	int	body	The page number starting from 1.	Yes
page_size	int	body	The number of entries per page. Maximum value: 100.	Yes
project_id	String	body	The project ID.	Yes
device_status	String[]	body	The device status. Expiring Exception Online Offline	No
device_types	int[]	body	The device type. -1: others 0: smart light 1: gateway 2: non-smart light 3: switch 4: sensor	No
top_categories	String[]	body	The code of the device status filter list, namely, the device category. dgzm: Electrical device zm: Lighting xjd: Small home appliance jjaf: Security and sensors wgzk: Gateway and central control qt: Others	No
room_id	String	body	The space ID.	No
device_name	String	body	The device name.	No
online	Boolean	body	Indicates whether the device is online. Valid values: false: The device is offline. true: The device is online.	No
upgrade_status	int[]	body	The update status. Valid values: 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated.	No

Response parameters

Parameter	Field type	Description
code	Integer	The error code on failure. The value is empty on success.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	unknown	The returned result.

Description of result

{
    "result": {
        "list": [
            {
                "custom_capability": "String // Custom protocol type: Wi-Fi, Zigbee, and Sigmesh",
                "device_id": "String // The device ID",
                "device_name": "String // The device name",
                "device_saas_id": "String // The unique ID of a commercial lighting device",
                "group_type":"List<Integer> // The device protocol type, 1: Wi-Fi, 2: Zigbee, 3: Sigmesh",
                "online": "Boolean // Indicates whether a device is online. false: offline, true: online",
                "room_name": "String // The space name",
                "top_category": "String // The top category to which the product belongs",
                "top_category_name": "String // The name of the top category to which the product belongs",
                "upgrade_status": "Integer // The update status. 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated",
                "version": "String // The available version of the firmware"
            }
        ],
        "total": "Integer // The total number"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

Sample request

{
    "project_id": "String // The project ID",
    "room_id": "String // The space ID",
    "page":1,
    "page_size":10
}

Sample response

{
    "result": {
        "list": [
            {
                "custom_capability": "String // Custom protocol type: Wi-Fi, Zigbee, and Sigmesh",
                "device_id": "String // The device ID",
                "device_name": "String // The device name",
                "device_saas_id": "String // The unique ID of a commercial lighting device",
                "group_type":"List<Integer> // The device protocol type, 1: Wi-Fi, 2: Zigbee, 3: Sigmesh",
                "online": "Boolean // Indicates whether a device is online. false: offline, true: online",
                "room_name": "String // The space name",
                "top_category": "String // The top category to which the product belongs",
                "top_category_name": "String // The name of the top category to which the product belongs",
                "upgrade_status": "Integer // The update status. 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated",
                "version": "String // The available version of the firmware"
            }
        ],
        "total": "Integer // The total number"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

Get the list of devices being updated via OTA

Functional description

Get the list of devices that are being updated via OTA.

API endpoint

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

Request parameters

Parameter	Field type	Parameter type	Description	Required
page	int	body	The page number starting from 1.	Yes
page_size	int	body	The number of entries per page. Maximum value: 100.	Yes
project_id	String	body	The project ID.	Yes
device_status	String[]	body	The device status. Expiring Exception Online Offline	No
device_types	int[]	body	The device type. -1: others 0: smart light 1: gateway 2: non-smart light 3: switch 4: sensor	No
top_categories	String[]	body	The code of the device status filter list, namely, the device category. dgzm: Electrical device zm: Lighting xjd: Small home appliance jjaf: Security and sensors wgzk: Gateway and central control qt: Others	No
room_id	String	body	The space ID.	No
device_name	String	body	The device name.	No
online	Boolean	body	Indicates whether the device is online. Valid values: false: The device is offline. true: The device is online.	No
upgrade_status	int[]	body	The update status. Valid values: 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated.	No

Response parameters

Parameter	Field type	Description
code	Integer	The error code on failure. The value is empty on success.
success	Boolean	Indicates whether the operation is successful. true: success. false: failure.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	unknown	The returned result.

Description of result

{
    "result": {
        "list": [
            {
                "custom_capability": "String // Custom protocol type: Wi-Fi, Zigbee, and Sigmesh",
                "device_id": "String // The device ID",
                "device_name": "String // The device name",
                "device_saas_id": "String // The unique ID of a commercial lighting device",
                "group_type":"List<Integer> // The device protocol type, 1: Wi-Fi, 2: Zigbee, 3: Sigmesh",
                "online": "Boolean // Indicates whether a device is online. false: offline, true: online",
                "room_name": "String // The space name",
                "top_category": "String // The top category to which the product belongs",
                "top_category_name": "String // The name of the top category to which the product belongs",
                "upgrade_status": "Integer // The update status. 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated",
                "version": "String // The available version of the firmware"
            }
        ],
        "total": "Integer // The total number"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

Sample request

{
    "project_id": "String // The project ID",
    "room_id": "String // The space ID",
    "page":1,
    "page_size":10
}

Sample response

{
    "result": {
        "list": [
            {
                "custom_capability": "String // Custom protocol type: Wi-Fi, Zigbee, and Sigmesh",
                "device_id": "String // The device ID",
                "device_name": "String // The device name",
                "device_saas_id": "String // The unique ID of a commercial lighting device",
                "group_type":"List<Integer> // The device protocol type, 1: Wi-Fi, 2: Zigbee, 3: Sigmesh",
                "online": "Boolean // Indicates whether a device is online. false: offline, true: online",
                "room_name": "String // The space name",
                "top_category": "String // The top category to which the product belongs",
                "top_category_name": "String // The name of the top category to which the product belongs",
                "upgrade_status": "Integer // The update status. 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated",
                "version": "String // The available version of the firmware"
            }
        ],
        "total": "Integer // The total number"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

Get the list of devices updated via OTA

Functional description

Get the list of devices that have been updated via OTA.

API endpoint

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

Request parameters

Parameter	Field type	Parameter type	Description	Required
page	int	body	The page number starting from 1.	Yes
page_size	int	body	The number of entries per page. Maximum value: 100.	Yes
project_id	String	body	The project ID.	Yes
device_status	String[]	body	The device status. Expiring Exception Online Offline	No
device_types	int[]	body	The device type. -1: others 0: smart light 1: gateway 2: non-smart light 3: switch 4: sensor	No
top_categories	String[]	body	The code of the device status filter list, namely, the device category. dgzm: Electrical device zm: Lighting xjd: Small home appliance jjaf: Security and sensors wgzk: Gateway and central control qt: Others	No
room_id	String	body	The space ID.	No
device_name	String	body	The device name.	No
online	Boolean	body	Indicates whether the device is online. Valid values: false: The device is offline. true: The device is online.	No
upgrade_status	int[]	body	The update status. Valid values: 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated.	No

Response parameters

Parameter	Type	Description
code	Integer	The error code on failure. The value is empty on success.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	unknown	The returned result.

Description of result

{
    "result": {
        "list": [
            {
                "custom_capability": "String // Custom protocol type: Wi-Fi, Zigbee, and Sigmesh",
                "device_id": "String // The device ID",
                "device_name": "String // The device name",
                "device_saas_id": "String // The unique ID of a commercial lighting device",
                "group_type":"List<Integer> // The device protocol type, 1: Wi-Fi, 2: Zigbee, 3: Sigmesh",
                "online": "Boolean // Indicates whether a device is online. false: offline, true: online",
                "room_name": "String // The space name",
                "top_category": "String // The top category to which the product belongs",
                "top_category_name": "String // The name of the top category to which the product belongs",
                "upgrade_status": "Integer // The update status. 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated",
                "version": "String // The available version of the firmware"
            }
        ],
        "total": "Integer // The total number"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

Sample request

{
    "project_id": "String // The project ID",
    "room_id": "String // The space ID",
    "page":1,
    "page_size":10
}

Sample response

{
    "result": {
        "list": [
            {
                "custom_capability": "String // Custom protocol type: Wi-Fi, Zigbee, and Sigmesh",
                "device_id": "String // The device ID",
                "device_name": "String // The device name",
                "device_saas_id": "String // The unique ID of a commercial lighting device",
                "group_type":"List<Integer> // The device protocol type, 1: Wi-Fi, 2: Zigbee, 3: Sigmesh",
                "online": "Boolean // Indicates whether a device is online. false: offline, true: online",
                "room_name": "String // The space name",
                "top_category": "String // The top category to which the product belongs",
                "top_category_name": "String // The name of the top category to which the product belongs",
                "upgrade_status": "Integer // The update status. 0: No update is available. 1: An update is available. 2: An update is in progress. 3: The device has been successfully updated. 4: Failed to update the device. 5: Wait for the device to be updated",
                "version": "String // The available version of the firmware"
            }
        ],
        "total": "Integer // The total number"
    },
    "success": true,
    "t": 1745492675295,
    "tid": "e7f1849b20fb11f0942fe62c0c16c951"
}

Sync devices to be updated in the space

Functional description

Sync devices to be updated in the space.

API endpoint

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

Request parameters

Parameter	Field type	Parameter type	Description	Required
project_id	String	body	The project ID.	Yes
room_id	String	body	The space ID.	Yes

Response parameters

Parameter	Field type	Description
code	Integer	The error code on failure. The value is empty on success.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	unknown	The returned result.

Description of result

Sample request

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

Sample response

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

Error codes

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error codes	Description
500	A system error has occurred while processing your request.