Generic Services

API list

Action	Description
device.name	Rename a device.
device.freeEditionLogs	Query device logs for free.
device.paidEditionLogs	Query device logs. This is the paid log service.
device.reset-factory	Restore factory defaults.
device.remove	Remove a device.
device.upgradeInfos	Query the current firmware and update information of a device.
device.upgrade	Confirm to start a device firmware update.

Rename a device

API endpoint

action: device.name

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
name	String	The instruction set.	Yes

Sample request

{
    "action": "device.name",
    "params": {
        "device_id": "vdevo158132564936223",
        "name": "Test cool and warm white light"
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Query device logs for free

API description

Query the operation logs of a specified device according to the specified criteria. The log service is provided for free.

API endpoint

action: device.freeEditionLogs

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
codes	String	One or more data points (DPs) supported by the specified device. Multiple data points are separated with commas (,). This parameter value is empty by default.	Yes
type	String	One or more types of logs that can be queried. Multiple event types of logs are separated with commas (,). This parameter is required. For more information, see Description of event types in Device logs.	Yes
start_row_key	String	The row key of the HBase table to be queried.	No
size	int	The number of entries to be returned per page. Default value: 20. Maximum value: 100.	No
start_time	Long	The start timestamp of the query.	Yes
end_time	Long	The end timestamp of the query.	Yes

Sample request

{
    "action": "device.freeEditionLogs",
    "params": {
            "device_id": "vdevo158132564936223",
                "codes": 'code1,code2',
                "type": "1,2",
            "size": 20,
                "start_time": 0,
                "end_time": 1585898159935
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.
t	Long	The timestamp.

Description of result

Parameter name	Type	Description
logs	Object	The log message body.
has_next	Boolean	Indicates whether the next entry is returned.
device_id	String	The device ID.
current_row_key	String	The current row key in the HBase table.
next_row_key	String	The row key of the next entry that meets the query criteria. If null is returned, no other logs meet the criteria.

Description of logs

Parameter name	Type	Description
code	String	The identifier of a DP.
value	String	The value of a DP.
event_time	String	The timestamp when an event occurs.
event_from	String	The source that triggers the event. For more information, see the Description of event sources in Device logs.
event_id	String	The type of event. For more information, see the Description of event types in Device logs.
status	String	Indicates whether the data is valid and not deleted. Default value: 1.

Sample response

{
    "success": true,
    "t": 1561344464370,
    "result": {
        "logs": [
            {
                "code": "switch_1",
                "value": "false",
                "event_time": 1560872567955,
                "event_from": "1",
                "event_id": 7
            },
            {
                "code": "switch_1",
                "value": "false",
                "event_time": 1560783276382,
                "event_from": "1",
                "event_id": 7
            }
        ],
        "device_id": "75500780ecfabc9a86f5",
        "has_next": true,
        "current_row_key": "NjUwODIzNDU1ZjY4YTljYmFmY2UwODcwMDU1N185MjIzMzcwNDc1OTgyMjA3ODUyXzdfMQ==",
        "next_row_key": "NjUwODIzNDU1ZjY4YTljYmFmY2UwODcwMDU1N185MjIzMzcwNDc2MDcxNDk5OTM0XzdfMQ=="
    }
}

Query device logs using paid log service

API description

Query the operation logs of a specified device according to the specified criteria. This is the paid log service.

API endpoint

action: device.paidEditionLogs

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
codes	String	One or more DPs supported by the specified device. Multiple data points are separated with commas (,). This parameter value is empty by default.	No
type	String	One or more types of logs that can be queried. Multiple event types of logs are separated with commas (,). This parameter is required. For more information, see Description of event types in Device logs.	Yes
last_row_key	String	The row key of the last entry on each page. By default, the value is empty to return the first page.	Yes
last_event_time	Long	The event occurrence time of the last entry on each page. By default, the value is empty to return the first page.	Yes
size	int	The number of entries to be returned per page. Default value: 20. Maximum value: 100.	No
start_time	Long	The start timestamp of the query.	Yes
end_time	Long	The end timestamp of the query.	Yes

Sample request

{
    "action": "device.paidEditionLogs",
    "params": {
                "device_id": "vdevo158132564936223",
                "type": "5",
                "last_row_key": "650823455f68a9cbafce08700557_9223370475075511414_1",
                "last_event_time": 1581779264393,
        "size": 20,
                "start_time": 0,
                "end_time": 1585898159935
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.
t	Long	The timestamp.

Description of result

Parameter name	Type	Description
logs	Object	The log message body.
has_next	Boolean	Indicates whether the next entry is returned.
device_id	String	The device ID.
count	Long	The total number of logs that meet the query criteria.

Description of logs

Parameter name	Type	Description
code	String	The identifier of a DP.
value	String	The value of a DP.
event_time	String	The timestamp when an event occurs.
event_from	String	The source that triggers the event. For more information, see the Description of event sources in Device logs.
event_id	String	The type of event. For more information, see the Description of event types in Device logs.
status	String	Indicates whether the data is valid and not deleted. Default value: 1.
row	String	The current row key in the HBase table.

Sample response

{
    "success":true,
        "t":1561344464370,
        "result":{
            "count":32,
            "device_id":"75500780ecfabc9a86f5",
            "has_next":true,
            "logs":[
                {
                    "event_id":1,
                    "event_time":1562031576431,
                    "event_from":"1",
                    "row":"650823455f68a9cbafce08700557_9223370474823199376_1",
                    "status":"1"
                },
                {
                    "event_id":1,
                    "event_time":1562031394665,
                    "event_from":"1",
                    "row":"650823455f68a9cbafce08700557_9223370474823381142_1",
                    "status":"1"
                },
                {
                    "event_id":1,
                    "event_time":1562031277824,
                    "event_from":"1",
                    "row":"650823455f68a9cbafce08700557_9223370474823497983_1",
                    "status":"1"
                },
                {
                    "event_id":1,
                    "event_time":1561935500636,
                    "event_from":"1",
                    "row":"650823455f68a9cbafce08700557_9223370474919275171_1",
                    "status":"1"
                }
            ]
        }
}

Device logs

Description of event sources

code	Description
1	The device.
2	The command from the client.
3	A third-party platform.
4	The command from the cloud.
-1	The unknown source.

Description of event types

code	Description
1	A device goes online.
2	A device goes offline.
3	A device is activated.
4	A device is reset.
5	A command is sent from the cloud to the device.
6	The firmware is updated.
7	DP status is reported.
8	The signal level of the device.
9	A device is restarted.
10	The information about a scheduled task.

Restore factory defaults

API description

Restore the factory default settings of a specified device based on the device ID.

API endpoint

action: device.reset-factory

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
    "action": "device.reset-factory",
    "params": {
        "device_id": "vdevo158132564936223"
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	The returned result.

Sample response

{
    "success": true,
    "t": 1550642917632,
    "result": true
}

Remove a device

API endpoint

action: device.remove

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
    "action": "device.remove",
    "params": {
        "device_id": "vdevo158346027181013"
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.

Query current firmware and update information of device

API endpoint

action: device.upgradeInfos

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes

Sample request

{
    "action": "device.upgradeInfos",
    "params": {
        "device_id": "vdevo158132564936223"
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The firmware and update information of the device.

Description of result

Parameter name	Type	Description
upgrade_status	Integer	The update status. Valid values: 0: No update is available. 1: The device is ready. 2: An update is in progress. 3: An update is completed. 4: An exception occurs during an update process.
current_version	String	The current version.
upgrade_version	String	The update version.
module_type	String	The type of module. Valid values: 0: Wi-Fi 1: Bluetooth LE 2: GPRS 9: MCU
module_desc	String	The description of a specified module.
last_upgrade_time	String	The time when the firmware was last updated.

Confirm starting firmware update

API endpoint

action: device.upgrade

Request parameter

Parameter name	Type	Description	Required
device_id	String	The device ID.	Yes
module_type	String	The type of module.	Yes

Sample request

{
    "action": "device.upgrade",
    "params": {
            "device_id": "vdevo158313016266290",
                "module_type": "0"
    }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. Valid values: true: success. false: failure.
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the operation is successful.