Generic Services

Last Updated on : 2024-06-05 03:15:11download

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.

If the API request failed and a permission denial was returned, check whether the specified device is still on the current account.

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.