Device Timing Management

Last Updated on : 2023-05-22 06:38:12download

This topic describes the related APIs of timing management.

API list

Request method	API	Description
POST	/v1.0/devices/{device_id}/timers	Add a timing task to the device
GET	/v1.0/devices/{device_id}/timers	Query the list of timing tasks of the device
GET	/v1.0/devices/{device_id}/timers /categories/{category}	Get the information of timing tasks in a specified category
PUT	/v1.0/devices/{device_id}/timers /groups/{group_id}	Update the information of a specified timing task group of the device
PUT	/v1.0/devices/{device_id}/timers /categories/{category}/groups/{group_id}/status	Update the status of a specified timing task group of the device
DELETE	/v1.0/devices/{device_id}/timers	Delete all timing tasks of the device
DELETE	/v1.0/devices/{device_id}/timers /categories/{category}	Delete the timing tasks in a specified category
DELETE	/v1.0/devices/{device_id}/timers /categories/{category}/groups/{group_id}	Delete the timing tasks of a specified task group in a specified category

Add a timing task to the device

API description

This interface is used to add timing tasks for a device. Use loops to determine a cyclic timing task or non-cyclic timing task.

Cyclic timing task: Take one week as a cycle, and you can set cyclic timing tasks from Monday to Sunday.
Non-cyclic timing task: Set a timing task on a specified time point, and the API will limit the set time point. The time point should be later than the current time., Otherwise, a timing task can not be created, and expired information will be prompted.

API address

POST /v1.0/devices/{device_id}/timers

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID.
category	String	BODY	Yes	Timing category.
loops	String	BODY	Yes	Return a 7-digit number consisting of 0 and 1 if the request failed. 0 represents closed, and 1 represents open. For example, `0000010` indicates that the task on Saturday is open and other days are closed.
time_zone	String	BODY	Yes	Time zone. For example, use `+08:00` for China.
timezone_id	String	BODY	Yes	Time zone ID, such as `Asia/shanghai`.
instruct	Array<instruct>	BODY	Yes	The specific time and device instructions of a timing task. Multiple tasks are allowed to be set simultaneously.
alias_name	String	BODY	No	Alias name.

Description of instruct

Parameter name	Data type	Required	Description
time	String	Yes	Executing time of a timing task
functions	Array<functions>	Yes	Instructions to be executed at a scheduled time
date	String	No Note: When `date` is passed in, `loops` will be `0000000`, and the format of `date` is 20181212.	Executing date of a timing task

Description of functions

Parameter name	Data type	Required	Description
code	String	Yes	The code of the instruction that is to be executed
value	Object	Yes	The value of the instruction that is to be executed

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
group_id	String	Timing task ID

Request example

POST  /v1.0/devices/vdevo153490924111111/timers
{
    "instruct":[
        {
            "functions":[
                {
                    "code":"switch_led",
                    "value":true
                },
                {
                	"code":"bright_value_v2",
                    "value":500
                }
            ],
            "date":"20200210",
            "time":"17:41"
        }
    ],
    "loops":"0000000",
    "category":"test",
    "timezone_id":"Asia/Shanghai",
    "time_zone":"+8:00"
}

SDK example

N/A

Return example

{ "success": true, "result": { "group_id": "000000****" } }

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission
1109	Illegal parameter

Query the list of timing task of the device

API description

This interface is used to query the list of timing task details of a specified device ID.

API address

GET /v1.0/devices/{device_id}/timers

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
groups	Array<groups>	The list of timing task information
category	Object<category>	Information of timing task category

Description of groups

Parameter name	Data type	Description
timers	Object<timers>	Timing task information
id	String	Timing task number

Description of category

Parameter name	Data type	Description
category	String	Timing task category
status	Integer	The status of a timing task category

Description of timers

Parameter name	Data type	Description
date	String	Date of the set timing task
timezone_id	String	Time zone ID
loops	String	Cyclic timing information
time	String	The set time
status	Integer	Status of the timing task 0: disabled 1: enabled 2: deleted
functions	Array<functions>	Instruction of timing
group_order	Integer	Specified order
timer_id	Integer	The unique identifier of timing information
alias_name	String	Remarks

Description of functions

Parameter name	Data type	Required	Description
code	String	Yes	The code of the instruction that is to be executed
value	Object	Yes	The value of the instruction that is to be executed

Request example

GET /v1.0/devices/vdevo154458004640011/timers

SDK example

N/A

Return example

{
    "result": [
        {
            "category": {
                "category": "test",
                "status": 1
            },
            "groups": [
                {
                    "id": "000000mwf3",
                    "timers": [
                        {
                            "alias_name": "",
                            "date": "20200210",
                            "functions": [
                                {
                                    "code": "bright_value_v2",
                                    "value": 5000
                                },
                                {
                                    "code": "switch_led",
                                    "value": true
                                }
                            ],
                            "group_order": 0,
                            "is_app_push": false,
                            "loops": "0000000",
                            "status": 0,
                            "time": "17:30",
                            "timer_id": 4906528,
                            "timezone_id": "Asia/Shanghai"
                        }
                    ]
                }
            ]
        }
    ],
    "success": true,
    "t": 1581336613789
}

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Get the timing task information of a specified category

API description

This interface is used to get the timing task information of a specified category under a specified device.

API address

GET /v1.0/devices/{device_id}/timers/categories/{category}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID
category	String	URI	Yes	Timing category

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Object<result>	The returned result.

Description of result

Parameter name	Data type	Description
groups	Array<groups>	The list of timing task information
category	Object<category>	The update time of device status

Description of groups

Parameter name	Data type	Description
timers	Object<timers>	Timing task information
id	String	Timing task number

Description of category

Parameter name	Data type	Description
category	String	Timing task category
status	Integer	The status of a timing task category

Description of timers

Parameter name	Data type	Description
date	String	Date of the set timing task
timezone_id	String	Time zone ID
loops	String	Cyclic timing information
time	String	The set time
status	Integer	Status of the timing task 0: disabled 1: enabled 2: deleted
functions	Array<functions>	Instruction of timing
group_order	Integer	Specified order
timer_id	Integer	The unique identifier of timing information
alias_name	String	Remarks

Description of functions

Parameter name	Data type	Required	Description
code	String	Yes	The code of the instruction that is to be executed
value	Object	Yes	The value of the instruction that is to be executed

Request example

GET /v1.0/devices/vdevo154458004640011/timers/categories/10

SDK example

N/A

Return example

{
    "result": [
        {
            "category": {
                "category": "test",
                "status": 1
            },
            "groups": [
                {
                    "id": "000000mwf3",
                    "timers": [
                        {
                            "alias_name": "",
                            "date": "20200202",
                            "functions": [
                                {
                                    "code": "bright_value_v2",
                                    "value": 5000
                                },
                                {
                                    "code": "switch_led",
                                    "value": true
                                }
                            ],
                            "group_order": 0,
                            "is_app_push": false,
                            "loops": "0000000",
                            "status": 0,
                            "time": "17:30",
                            "timer_id": 4906528,
                            "timezone_id": "Asia/Shanghai"
                        }
                    ]
                }
            ]
        }
    ],
    "success": true,
    "t": 1581336613789
}

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Update the information of a specified timing task group of the device

API description

This interface is used to update the information of a specified timing task group of the device.

API address

PUT /v1.0/devices/{device_id}/timers/groups/{group_id}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID.
group_id	String	URI	Yes	Timing task group ID
loops	String	BODY	Yes	A 7-digit number consisting of 0 and 1. 0 means closed, and 1 means open. For example, `0000010` indicates that the task on Saturday is open and other days are closed.
category	String	BODY	Yes	Timing task category
time_zone	String	BODY	Yes	Time zone. For example, use `+08:00` for China.
timezone_id	String	BODY	Yes	Time zone ID, such as `Asia/shanghai`.
instruct	Array<instruct>	BODY	Yes	The specified time and device instructions of a timing task. Multiple tasks are allowed to be set simultaneously.
alias_name	String	BODY	No	Alias name.

Description of instruct

Parameter name	Data type	Required	Description
time	String	Yes	Executing time of a timing task
functions	Array<functions>	Yes	Instructions to be executed at a scheduled time
date	String	No Note: When `date` is passed in, `loops` will be `0000000`, and the format of `date` is 20181212.	Executing date of a timing task

Description of functions

Parameter name	Data type	Required	Description
code	String	Yes	The code of the instruction that is to be executed
value	Object	Yes	The value of the instruction that is to be executed

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Boolean	Determine whether the request succeeded or not. It will return null if it failed.

Request example

PUT /v1.0/devices/vdevo154458004640011/timers/groups/100
      
{
    "loops":"0001000",
    "time_zone":"+08:00",
    "timezone_id":"Asia/ShangHai",
    "category":"test",
    "instruct":[
        {
            "time":"12:00",
            "date":"20181212",
            "functions":[
                {
                    "code":"switch",
                    "value":true
                },
                {
                    "code":"bright",
                    "value":100
                }
            ]
        },
        {
            "time":"12:10",
            "date":"20181212",
            "functions":[
                {
                    "code":"switch",
                    "value":false
                }
            ]
        }
    ]
}

SDK example

N/A

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Update the status of a specified timing task group of the device

API description

This interface is used to update the status of the device timing task group.

API address

PUT /v1.0/devices/{device_id}/timers/categories/{category}/groups/{group_id}/status

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID
group_id	String	URI	Yes	Timing task group ID
category	String	URI	Yes	Timing task group category
value	String	BODY	Yes	Timing task status 0: disabled 1: enabled 2: deleted

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Boolean	Determine whether the request succeeded or not. It will return null if it failed.

Request example

PUT /v1.0/devices/vdevo154458004640011/timers/categories/100/groups/0000002ftg/status
{
	"value": "0"
}

SDK example

TuyaClient client = new TuyaClient(clientId, secret, RegionEnum.CN);
List<DeviceVo> deviceFunctions = client.getUserDevices(UID);
System.out.println("Get the device list of the user: ");
System.out.println(JSONObject.toJSONString(deviceFunctions));

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Delete all timing tasks of the device

API description

This interface is used to delete all timing tasks of the device.

API address

DELETE /v1.0/devices/{device_id}/timers

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Boolean	Determine whether the request succeeded or not. It will return null if it failed.

Request example

DELETE /v1.0/devices/vdevo154458004640011/timers

SDK example

N/A

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Delete the timing tasks in a specified category

API description

This interface is used to delete the timing task in a specified category.

API address

DELETE /v1.0/devices/{device_id}/timers/categories/{category}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID
category	String	URI	Yes	Timing task group category

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Boolean	Determine whether the request succeeded or not. It will return null if it failed.

Request example

DELETE /v1.0/devices/vdevo154458004640011/timers/categories/100

SDK example

N/A

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Delete the timing task of a specified timing group in a specified category

API description

Delete the timing task of a specified timing group in a specified category.

API address

DELETE /v1.0/devices/{device_id}/timers/categories/{category}/groups/{group_id}

Request parameter

Parameter name	Data type	Parameter type	Required	Description
device_id	String	URI	Yes	Device ID
category	String	URI	Yes	Timing task category
group_id	String	URI	Yes	Timing task group ID

Return parameter

Parameter name	Data type	Description
code	Integer	Response code. See Error code.
success	Boolean	Determine whether the request succeeded or not. true: succeeded false: failed
msg	String	The message returned if the request fails. It will return null if the request succeeds.
result	Boolean	Determine whether the request succeeded or not. It will return null if it failed.

Request example

DELETE /v1.0/devices/vdevo154458004640011/timers/categories/100/groups/0000002ftg

SDK example

N/A

Return example

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

Error code

The following are common service exceptions for this interface. For more exception errors, see Error Code.

Error code	Description
500	System error
1106	Illegal permission

Prev DocSmart Home Scene Linkage

Next DocScene Automation