Scene Automation

Last Updated on : 2023-07-18 10:19:40download

API list

Request method	API	Description
GET	/v1.1/homes/{home_id}/scenes	Query scenes in a home
GET	/v1.0/scenes/default-pictures	Query default scene images
POST	/v1.0/homes/{home_id}/scenes/{scene_id}/trigger	Trigger a scene
POST	/v1.0/homes/{home_id}/scenes	Add a scene
DELETE	/v1.0/homes/{home_id}/scenes/{scene_id}	Delete a scene
PUT	/v1.0/homes/{home_id}/scenes/{scene_id}	Modify a scene
GET	/v1.0/homes/{home_id}/scene/devices	Query devices that support scenes in a home
GET	/v1.0/devices/{device_id}/enable-linkage/codes	Get supported linkage conditions
POST	/v1.0/devices/{device_id}/scenes/{scene_id}	Bind a scene
DELETE	/v1.0/devices/{device_id}/scenes/{scene_id}	Unbind a scene
GET	/v1.0/devices/{device_id}/scenes	Query scenes bound with a device
POST	/v1.0/homes/{home_id}/automations	Add an automation scene
PUT	/v1.0/homes/{home_id}/automations /{automation_id}	Modify an automation scene
DELETE	/v1.0/homes/{home_id}/automations /{automation_id}	Delete an automation scene
GET	/v1.1/homes/{home_id}/automations	Query automation scenes
GET	/v1.0/homes/{home_id}/automations /{automation_id}	Query an automation scene in a home
POST	/v1.0/homes/{home_id}/automations /{automation_id}/conditions/trigger	Query external conditions triggering an automation scene in a home
GET	/v1.0/homes/{home_id}/automation /devices	Query devices that support an automation scene in a home
GET	/v1.0/homes/automation/weather/conditions	Query weather conditions supported by an automation scene
GET	/v1.0/homes/{home_id}/enable-linkage/codes	Query actions supported in a home
PUT	/v1.0/homes/{home_id}/automations /{automation_id}/actions/enable	Enable an automation scene
PUT	/v1.0/homes/{home_id}/automations /{automation_id}/actions/disable	Disable an automation scene

Query scenes in a home

API description

Query a list of scenes in the specified home.

API endpoint

GET /v1.1/homes/{home_id}/scenes

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The home ID.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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.

Result

Parameter	Type	Description
scene_id	String	The scene ID.
name	String	The scene name.
background	String	The background image.
enabled	Boolean	Indicates whether it is enabled.
status	String	The status. Valid values: `1`: normal. `2`: expired.
actions	List	A list of actions.

Actions

Parameter	Type	Description
entity_id	String	The device ID.
executor_property	JSON	The property of the specified execution action.
action_executor	String	The type of action. Valid value: `dpIssue`.

Sample request

GET /v1.1/homes/5270711/scenes

Sample response

{
    "success":true,
    "t":1541071460239,
    "result":[
        {
            "scene_id":"53IYSXI3gEn2w***",
            "enabled": true,
            "status":"1",
            "name":"Turn on light bulb",
            "background":"https://images.tuyacn.com/smart/rule/cover/starry.png",
            "actions":[
                {
                    "entity_id":"0120090568c63a89****",
                    "executor_property":{
                        "work_mode":"scene_2"
                    },
                    "action_executor":"dpIssue"
                }
            ]
        },
        {
            "scene_id":"DKgx28KbdPfz****",
            "name":"Morning",
            "background":"https://images.tuyacn.com/smart/rule/cover/****.png",
            "actions":[
                {
                    "entity_id":"012000715ccf7f4f****",
                    "executor_property":{
                        "switch_led":true
                    },
                    "action_executor":"dpIssue"
                }
            ]
        }
    ]
}

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.
1106	Invalid permission.

Query default scene images

API description

Query a list of default scene images.

API endpoint

GET /v1.0/scenes/default-pictures

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	List	A list of returned URLs of scene images.

Sample request

GET /v1.0/scenes/default-pictures

Sample response

{
   "success":true,
   "t":1541071460239,
   "result":[
       "https://images.tuyacn.com/smart/rule/cover/starry.png",
       "https://images.tuyacn.com/smart/rule/cover/sport.png"
   ]
}

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Trigger a scene

API description

Trigger and run the specified scene.

API endpoint

POST /v1.0/homes/{home_id}/scenes/{scene_id}/trigger

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The home ID.	Yes
scene_id	String	URI	The scene ID.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	Indicates whether the scene is triggered successfully. `true` is returned when the operation is successful.

Sample request

POST /v1.0/homes/242****/scenes/53IYSXI3gEn2w3Oc/trigger

Sample response

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

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Delete a scene

API description

Delete a scene of the specified home.

API endpoint

DELETE /v1.0/homes/{home_id}/scenes/{scene_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The home ID.	Yes
scene_id	String	URI	The scene ID.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	Indicates whether the scene is deleted successfully. `true` is returned when the operation is successful.

Sample request

DELETE /v1.0/homes/242****/scenes/53IYSXI3gEn2****

Sample response

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

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Add a scene

API description

Add a scene under the specified home.

API endpoint

POST /v1.0/homes/{home_id}/scenes

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	String	URI	The home ID.	Yes
name	String	Body	The scene name.	Yes
background	String	Body	The background image.	Yes
actions	List	Body	A list of actions.	Yes

Description of devices involved in actions

Parameter	Type	Description	Required
entity_id	String	The device ID.	Yes
executor_property	JSON	The property of the specified execution action.	No
action_executor	String	The type of the specified execution action.	Yes

Description of actions

Device actions
- entity_id: the device ID.
- action_executor: dpIssue.
- executor_property: standard instruction.
Delayed action
- entity_id: the device ID.
- action_executor: delay.
- executor_property: the delay parameter.
Disable an automation scene
- entity_id: the ID of an automation scene.
- action_executor: ruleDisable.
- executor_property: leave this field empty.
Enable an automation scene
- entity_id: the ID of an automation scene.
- action_executor: ruleEnable.
- executor_property: leave this field empty.

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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 scene ID.

Sample request

POST /v1.0/homes/242****/scenes
{
    "name": "Test of Adding a Scene",
    "background":"https://images.tuyacn.com/smart/rule/cover/sport.png",
    "actions":[
        {
             "executor_property":{
                  "hours":"0",
                  "minutes": "0",
                  "seconds": "5"
              },
             "action_executor":"delay"
        },
        {
            "executor_property":{
                "work_mode":"scene_2"
            },
            "action_executor":"dpIssue",
            "entity_id":"0120090568c63a89****"
        },
	{
                    "action_executor": "ruleDisable",
                    "entity_id": "AYJV2hh3eqm3****"
         },
	{
                    "action_executor": "ruleEnable",
                    "entity_id": "AYJV2hh3eqm3****"
         }
    ]
}

Sample response

{
 "success": true,
 "t": 1541072348540,
 "result":"53IYSXI3gEn2****"
}

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Modify a scene

API description

Modify a scene under the specified home.

API endpoint

PUT /v1.0/homes/{home_id}/scenes/{scene_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The home ID.	Yes
scene_id	String	Body	The scene ID.	Yes
name	String	Body	The scene name.	Yes
background	String	Body	The background image.	Yes
actions	List	Body	A list of actions.	Yes

Description of devices involved in actions

Parameter	Type	Description	Required
entity_id	String	The device ID.	Yes
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: `dpIssue`.	Yes

Description of delay in actions

Parameter	Type	Description	Required
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: `delay`.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	`true` is returned when the operation is successful.

Sample request

PUT /v1.0/homes/242****/scenes/53IYSXI3gEn2****    
{
    "name": "Test of Adding a Scene",
    "background":"https://images.tuyacn.com/smart/rule/cover/sport.png",
    "actions":[
    	{
            "executor_property":{
                "hours":"0",
                "minutes":"0",
                "seconds":"5"
            },
            "action_executor":"delay"
        },
        {
            "executor_property":{
                "work_mode":"scene_2"
            },
            "action_executor":"dpIssue",
            "entity_id":"0120090568c63a89****"
        }
    ]
}

Sample response

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

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Query devices that support scenes in a home

API description

Query a list of devices that support scenes in the specified home.

API endpoint

GET /v1.0/homes/{home_id}/scene/devices

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	List	The returned result.

Result

Parameter	Type	Description
device_id	String	The device ID.
uuid	String	The universally unique identifier (UUID) of the specified device.
name	String	The name.
home_id	String	The home ID.
product_id	String	The product ID.

Sample request

GET /v1.0/homes/2422121/scene/devices

Sample response on success

{
    "result":[
    	{
    		"id":"vedo123****",
    		"uuid":"asdfghnbvcx****",
        	"name":"Test Device",
    		"product_id":"r4567543****",
    		"home_id":"242****"
    	}
    ],
    "success":true,
    "t":1572936751228
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Bind a scene

API description

This API applies to scene switch devices. The scene switches have corresponding switch buttons, and each switch button has the specified instructions. With this API operation, the specified switch instruction can be bound with a sceneThis way, the scene switch is associated with the scene. Then, the scene can be directly triggered after an instruction is sent in the API request.

API endpoint

POST /v1.0/devices/{device_id}/scenes/{scene_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
scene_id	String	URI	The scene ID.	Yes
device_id	String	URI	The device ID.	Yes
code	String	Body	The code of a standard instruction.	Yes
value	String	BODY	The input parameter range of the specified instruction.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	Long	The room ID indicated by `room_id`.

Result

Parameter	Type	Description
Success	Boolean	Indicates whether the operation is successful.

Sample request

POST /v1.0/devices/vdevo1575XXXX00013095/scenes/EqFkQ79XXXXXtjlkTm
{
	"code":"scene_1",
	"value":"scene"
}

Sample response

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

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Unbind a scene

API description

This API applies to scene switch devices. After binding, a switch in the scene switch can be unbound from the specified scene.

API endpoint

DELETE /v1.0/devices/{device_id}/scenes/{scene_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes
scene_id	String	URI	The scene ID.	Yes
code	String	BODY	The code of a standard instruction. This value corresponds with the scene switch button.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	Long	The room ID indicated by `room_id`.

Result

Parameter	Type	Description
Success	Boolean	Indicates whether the operation is successful.

Sample request

DELETE /v1.0/devices/vdevo1575XXXX00013095/scenes/EqFkQ79XXXXXtjlkTm
{
	"code":"scene_1"
}

Sample response

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

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Query scenes bound with a device

API description

This API applies to scene switch devices. Query a list of scenes bound with the specified device based on the ID of the scene switch device.

API endpoint

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

Request parameters

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
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	Long	The room ID indicated by `room_id`.

Result

Parameter	Type	Description
device_id	Boolean	The device ID.
scenes	Object	A list of scenes bound with the device.

Scenes

Parameter	Type	Description
scene_id	String	The scene ID.
name	String	The scene name.
code	String	The binding instruction. This field applies to scene switch devices. Each switch corresponds with a standard instruction.
value	Object	The input parameter range of the specified instruction.

Sample request

GET /v1.0/devices/vdevo15758XXXX13095/scenes

Sample response

{
    "result": {
        "device_id": "vdevo15758****13095",
        "scenes": [
            {
                "code": "scene_2",
                "name": "Test of Adding Scene G-Turn off Light",
                "scene_id": "ilCZllmbXXXPO***",
                "value": "scene"
            },
            {
                "code": "scene_1",
                "name": "Scene of Turning on Light",
                "scene_id": "EqFkQ79uXXXjl***",
                "value": "scene"
            }
        ]
    },
    "success": true,
    "t": 1576036860284
}

Error codes

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

Error code	Description
500	A system error has occurred while processing your request.
1106	Invalid permission.

Add an automation scene

API description

Add an automation scene to the specified home.

API endpoint

POST /v1.0/homes/{home_id}/automations

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes
name	String	Body	The name of the specified automation scene.	Yes
background	String	Body	The background image.	Yes
conditions	List	Body	A list of scene conditions.	Yes
actions	List	Body	A list of actions.	Yes
match_type	Integer	Body	Indicates the matching types. Valid values: 1: Trigger a scene when any condition is met. 2: Trigger a scene when all conditions are met. 3: Trigger a scene when the custom conditions are met. Set the logic operation parameter `condition_rule`.	Yes
condition_rule	String	String	Custom condition rules. This parameter is required when the value of `match_type` is `3`. The custom condition rules follow the AND OR formula. Each automation condition is identified by its `order_num`.	No
preconditions	List	Body	The preconditions with the highest priority.	No

Note: For example, order_num in condition_rule is 1, 2, and 3 in turn. The business scenario is as follows: If you want to trigger an automation scene when conditions 1 and 2 are met simultaneously, or when condition 3 is met, then the expression is 1&&2||3.

Conditions

Parameter	Type	Description	Required
entity_type	Integer	The type of condition. The following condition types are supported: `1`: device status condition. `15`: external condition. `3`: weather condition. `6`: scheduled task condition.	Yes
display	JSON	Shows the conditions.	Yes
order_num	Integer	The serial number of the specified condition, starting from 1.	Yes
entity_id	String	The ID of the specified entity that executes the action. Valid values: When the value of `entity_type` is `1`, the value of `entity_id` is the device ID. Required. When the value of `entity_type` is `15`, the value of `entity_id` is automatically generated by the system. When the value of `entity_type` is `3`, the value of `entity_id` is the city ID. When the value of `entity_type` is `6`, the value of `entity_id` is `timer`.	No

Display device status conditions

Parameter	Type	Description	Required
code	String	The `statusCode` of the specified device.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The value of the specified code.	Yes

Display external conditions

Parameter	Type	Description	Required
code	String	The key of the specified external condition.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	Object	The code value for the key of the specified external condition.	Yes

Display weather conditions

Parameter	Type	Description	Required
code	String	The key of the specified weather condition. For example, `temp`.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The code value for the key of the specified weather condition.	Yes

Display scheduled task conditions

Parameter	Type	Description	Required
date	String	The date when a scheduled task is triggered, in the format of `yyyyMMdd`. For example, `20191125`.	Yes
loops	String	A seven-digit number consisting of 0 and 1. 0 means disabled and 1 means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
time	String	The time when a scheduled task is triggered, in the format of 24-hour time. For example, `14:00`.	Yes
timezone_id	String	The time zone ID. For example, `Asia/Shanghai`.	Yes

Description of preconditions

The preconditions. You can set the specified time period as a precondition.

Parameter	Type	Description	Required
cond_type	String	Currently, you can only set the specified time period as a precondition. Valid value: `timeCheck`.	Yes
display	JSON	Shows the conditions.	Yes

Description of display in preconditions

Parameter	Type	Description	Required
start	String	The start time in the format of 24-hour time. The default value is a time point of the day. For example, `10:00`.	Yes
end	String	The end time in the format of 24-hour time. For example, `22:00`.	Yes
loops	String	A seven-digit number consisting of 0 and 1. 0 means disabled and 1 means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
timezone_id	String	The time zone ID. For example, `Asia/Shanghai`.	Yes

Description of actions

Parameter	Type	Description	Required
entity_id	String	The device ID.	Yes
executor_property	JSON	The property of the specified execution action.	No
action_executor	String	The type of the specified execution action.	Yes

Device actions
- entity_id: the device ID.
- action_executor: dpIssue.
- executor_property: standard instruction.
Disable an automation scene
- entity_id: the ID of an automation scene.
- action_executor: ruleDisable.
- executor_property: leave this field empty.
Enable an automation scene
- entity_id: the ID of an automation scene.
- action_executor: ruleEnable.
- executor_property: leave this field empty.
Trigger a scene
- entity_id: the scene ID.
- action_executor: ruleTrigger
- executor_property: leave this field empty.

Sample request

POST /v1.0/homes/242****/automations

{
    "conditions":[
        {
            "display":{
                "code":"switch_1",
                "operator":"==",
                "value":true
            },
            "entity_id":"vdevo15725982542****",
            "entity_type":1,
            "order_num":1
        }
    ],
    "actions":[
    {
                "action_executor":"delay",
                "executor_property":{
    			  "hours": "0",
    			  "minutes": "0",
    			  "seconds": "5"
                }
            },
        {
            "action_executor":"dpIssue",
          	"entity_id":"vdevo15725982542****",
            "executor_property":{
			  "switch_1": true
            }
        }
    ],
    "background":"https://images.tuyacn.com/smart/rule/cover/bedroom.png",
    "match_type":1,
    "name":"Automation Test",
}

Example of preconditions

{
    "preconditions":[
        {
            "display":{
                "start":"10:00",
                "end":"12:00",
                "loops":"0010000",
                "timezone_id":"Asia/Shanghai"
            },
            "cond_type":"timeCheck"
        }
    ]
}

Example of device status conditions

{
    "conditions":[
        {
            "display":{
                "code":"switch_1",
                "operator":"==",
                "value":true
            },
            "entity_id":"vdevo15725982542****",
            "entity_type":1,
            "order_num":1
        }
    ]
}

Example of external conditions

{
    "conditions":[
        {
            "display":{
                "code":"test",
                "operator":"==",
                "value":"test"
            },
            "entity_type":15,
            "order_num":1
        }
    ]
}

Example of weather conditions

{
  "conditions":[
        {
            "display":{
                "code":"temp",
                "operator":"==",
                "value":"20"
            },
            "entity_id":"10",
            "entity_type":3,
            "order_num":1
        }
    ]
}

Example of scheduled task conditions

{
  "conditions":[
        {
            "display":{
                "date":"20200301",
                "loops":"0000000",
                "time":"14:00",
                "timezone_id":"Asia/Shanghai"
            },
            "entity_id":"timer",
            "entity_type":6,
            "order_num":1
        }
    ]
}

Example of external actions

{
    "actions":[
        {
            "action_executor":"externalAction",
            "executor_property":{
              // Custom, to be pushed through the message queue
            }
        }
    ]
}

Mapping between code data types and operators

type	operator
Boolean	“==”
Integer	“>”,“==”,“<”
Enum	“==”

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	String	The ID of the specified automation scene.

Sample response on success

{
    "success": true,
    "t": 1541072348540,
    "result":"53IYSXI3gEn2w3Oc"
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Modify an automation scene

API description

Modify automation scene configurations of the specified home.

API endpoint

PUT /v1.0/homes/{home_id}/automations/{automation_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes
automation_id	String	URI	The ID of the specified automation scene.	Yes
name	String	Body	The name of the specified automation scene.	Yes
background	String	Body	The background image.	Yes
conditions	List	Body	A list of scene conditions.	Yes
actions	List	Body	A list of actions.	Yes
match_type	Integer	Body	Indicates the matching types. Valid values: `1`: Trigger a scene when any condition is met. `2`: Trigger a scene when all conditions are met. `3`: Trigger a scene when the custom conditions are met. Set the logic operation parameter `condition_rule`.	Yes
condition_rule	String	String	The custom condition rule. This parameter is required when the value of `match_type` is `3`. The custom condition rules follow the AND OR formula. Each automation condition is identified by its `order_num`.	No
preconditions	List	Body	The preconditions with the highest priority.	No

Note: For example, order_num in condition_rule is 1, 2, and 3 in turn. The business scenario is as follows: If you want to trigger an automation scene when conditions 1 and 2 are met simultaneously, or when condition 3 is met, then the expression is 1&&2||3.

Conditions

Parameter	Type	Description	Required
entity_type	Integer	The type of condition. The following condition types are supported: `1`: Trigger by the specified device status. `15`: Trigger by the specified external condition. `3`: Trigger by the specified weather condition. `6`: Trigger by the specified scheduled task.	Yes
display	JSON	Shows the conditions.	Yes
order_num	Integer	The serial number of the specified condition, starting from `1`.	Yes
entity_id	String	The ID of the specified entity that executes the action. Valid values: When the value of `entity_type` is `1`, the value of `entity_id` is the device ID. In this case, this parameter is required. When the value of `entity_type` is `15`, the value of `entity_id` is automatically generated by the system. When the value of `entity_type` is `3`, the value of `entity_id` is the city ID. When the value of `entity_type` is `6`, the value of `entity_id` is `timer`.	No

Display device status conditions

Parameter	Type	Description	Required
code	String	The `statusCode` of the specified device.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The value of the specified code.	Yes

Display external conditions

Parameter	Type	Description	Required
code	String	The key of the specified external condition.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	Object	The code value for the key of the specified external condition.	Yes

Display weather conditions

Parameter	Type	Description	Required
code	String	The key of the specified weather condition. For example, `temp`.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The code value for the key of the specified weather condition.	Yes

Display scheduled task conditions

Parameter	Type	Description	Required
date	String	The date when a scheduled task is triggered, in the format of `yyyyMMdd`. For example, `20191125`.	Yes
loops	String	A seven-digit number consisting of `0` and `1`. `0` means disabled and `1` means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
time	String	The trigger time in the format of 24-hour time. For example, `14:00`.	Yes
timezone_id	String	The time zone ID. Fo example, `Asia/Shanghai`.	Yes

Description of preconditions

The preconditions. You can set the specified time period as a precondition.

Parameter	Type	Description	Required
cond_type	String	Currently, you can only set the specified time period as a precondition. Valid value: `timeCheck`.	Yes
display	JSON	Shows the conditions.	Yes

Description of display in preconditions

Parameter	Type	Description	Required
start	String	The start time in the format of 24-hour time. The default value is a time point of the day. For example, `10:00`.	Yes
end	String	The end time in the format of 24-hour time. For example, `22:00`.	Yes
loops	String	A seven-digit number consisting of `0` and `1`. `0` means disabled and `1` means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
timezone_id	String	The time zone ID. For example, `Asia/Shanghai`.	Yes

Description of devices involved in actions

Parameter	Type	Description	Required
entity_id	String	The device ID.	Yes
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: `dpIssue`.	Yes

Description of external actions

Parameter	Type	Description	Required
executor_property	JSON	A custom external action.	Yes
action_executor	String	The type of action. Valid value: `externalAction`.	Yes

Description of delay in actions

Parameter	Type	Description	Required
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: `delay`.	Yes

Sample request

PUT /v1.0/homes/242****/automations/53IYSXI3gEn2w3Oc

{
            "actions":[
               {
                                   "action_executor":"delay",
                                   "executor_property":{
                                   	"hours":"0",
                                   	"minutes": "0",
                                   	"seconds": "5"
                                   }
                                
                               },
                {
                    "action_executor":"dpIssue",
                    "entity_id":"vdevo15725982542****",
                    "executor_property":{
                    	"switch_1":true
                    }
                 
                },
              	{
                    "action_executor":"externalAction",
                    "executor_property":{
                    	// Subject to your customization
                    }
                 
                }
            ],
          
            "background":"https://images.tuyacn.com/smart/rule/cover/bedroom.png",
            "conditions":[
               
               {
                    "display":{
                        "code":"switch_1",
                        "operator":"==",
                        "value":true
                    },
                    "entity_id":"vdevo15725982542****",
                    "entity_type":1,
                    "order_num":1
                },
                {
                    "display":{
                        "code":"mode",
                        "operator":"==",
                        "value":1
                    },
                    "entity_type":15,
                    "order_num":2
                }
            ],
            "match_type":1,
            "name":"Automation Test",
        }

Example of preconditions

{
    "preconditions":[
        {
            "display":{
                "start":"10:00",
                "end":"12:00",
                "loops":"0000000",
                "timezone_id":"Asia/Shanghai"
            },
            "cond_type":"timeCheck"
        }
    ]
}

Example of device status conditions

{
    "conditions":[
        {
            "display":{
                "code":"switch_1",
                "operator":"==",
                "value":true
            },
            "entity_id":"vdevo15725982542****",
            "entity_type":1,
            "order_num":1
        }
    ]
}

Example of external conditions

{
    "conditions":[
        {
            "display":{
                "code":"test",
                "operator":"==",
                "value":"test"
            },
            "entity_type":15,
            "order_num":1
        }
    ]
}

Example of weather conditions

{
  "conditions":[
        {
            "display":{
                "code":"temp",
                "operator":"==",
                "value":"20"
            },
            "entity_id":"10",
            "entity_type":3,
            "order_num":1
        }
    ]
}

Example of scheduled task conditions

{
  "conditions":[
        {
            "display":{
                "date":"20200301",
                "loops":"0000000",
                "time":"14:00",
                "timezone_id":"Asia/Shanghai"
            },
            "entity_id":"timer",
            "entity_type":6,
            "order_num":1
        }
    ]
}

Example of external actions

{
    "actions":[
        {
            "action_executor":"externalAction",
            "executor_property":{
              // Custom, to be pushed through the message queue
            }
        }
    ]
}

Example of delay actions

{
   "action_executor":"delay",
   "executor_property":{
    "hours":"0",
    "minutes": "0",
    "seconds": "5"
   }

}

Mapping between code data types and operators

type	operator
Boolean	“==”
Integer	“>”,“==”,“<”
Enum	“==”

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	String	`true` is returned when the operation is successful.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Delete an automation scene

API description

Delete automation scene configurations of the specified home.

API endpoint

DELETE /v1.0/homes/{home_id}/automations/{automation_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes
automation_id	String	URI	The automation scene ID.	Yes

Sample request

DELETE /v1.0/homes/242****/automations/53IYSXI3gEn2w3Oc

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	String	Indicates whether the automation scene is deleted successfully. `true` is returned when the operation is successful.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Query automation scenes

API description

Query a list of automation scenes.

API endpoint

GET /v1.1/homes/{home_id}/automations

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes

Sample request

GET /v1.1/homes/242****/automations

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	List	The returned result.

Result

Parameter	Type	Description
automation_id	String	The ID of the specified automation scene.
name	String	The name of the specified automation scene.
enabled	Boolean	The enabling status.
status	String	The status. Valid values: `1`: normal, `2`: expired.
background	String	The background image.
conditions	List	A list of scene conditions.
preconditions	List	The precondition.
actions	List	A list of actions.
match_type	Integer	Indicates the matching types. Valid values: `1`: Trigger a scene when any condition is met. `2`: Trigger a scene when all conditions are met. `3`: Trigger a scene when the custom conditions are met. Set the logic operation parameter `condition_rule`.
condition_rule	String	The custom condition rule. This parameter is required when the value of `match_type` is `3`. The custom condition rules follow the AND OR formula. Each automation condition is identified by its `order_num`.

Conditions

Parameter	Type	Description	Required
entity_type	Integer	The type of condition. The following condition types are supported: `1`: Trigger by the specified device status. `15`: Trigger by the specified external condition. `3`: Trigger by the specified weather condition. `6`: Trigger by the specified scheduled task.	Yes
display	JSON	Shows the conditions.	Yes
order_num	Integer	The serial number of the specified condition, starting from `1`.	Yes
entity_id	String	The ID of the specified entity that executes the action. Valid values: When the value of `entity_type` is `1`, the value of `entity_id` is the device ID. In this case, this parameter is required. When the value of `entity_type` is `15`, the value of `entity_id` is automatically generated by the system. When the value of `entity_type` is `3`, the value of `entity_id` is the city ID. When the value of `entity_type` is `6`, the value of `entity_id` is `timer`.	No

Display device status conditions

Parameter	Type	Description	Required
code	String	The `statusCode` of the specified device.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The value of the specified code.	Yes

Display external conditions

Parameter	Type	Description	Required
code	String	The key of the specified external condition.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	Object	The code value for the key of the specified external condition.	Yes

Display weather conditions

Parameter	Type	Description	Required
code	String	The key of the specified weather condition. For example, `temp`.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The code value for the key of the specified weather condition.	Yes

Display scheduled task conditions

Parameter	Type	Description	Required
date	String	The date when a scheduled task is triggered, in the format of `yyyyMMdd`. For example, `20191125`.	Yes
loops	String	A seven-digit number consisting of `0` and `1`. `0` means disabled and `1` means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
time	String	The trigger time in the format of 24-hour time. For example, `14:00`.	Yes
timezone_id	String	The time zone ID. Fo example, `Asia/Shanghai`.	Yes

Description of preconditions

The preconditions. You can set the specified time period as a precondition.

Parameter	Type	Description	Required
cond_type	String	Currently, you can only set the specified time period as a precondition. Valid value: `timeCheck`.	Yes
display	JSON	Shows the conditions.	Yes

Description of display in preconditions

Parameter	Type	Description	Required
start	String	The start time in the format of 24-hour time. The default value is a time point of the day. For example, `10:00`.	Yes
end	String	The end time in the format of 24-hour time. For example, `22:00`.	Yes
loops	String	A seven-digit number consisting of `0` and `1`. `0` means disabled and `1` means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
timezone_id	String	The time zone ID. Fo example, `Asia/Shanghai`.	Yes

Description of devices involved in actions

Parameter	Type	Description	Required
entity_id	String	The device ID.	Yes
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: `dpIssue`.	Yes

Description of external actions

Parameter	Type	Description	Required
executor_property	JSON	A custom external action.	Yes
action_executor	String	The type of action. Valid value: `externalAction`.	Yes

Mapping between code data types and operators

type	operator
Boolean	“==”
Integer	“>”,“==”,“<”
Enum	“==”

Sample response on success

{
    "result":[
        {
            "actions":[
                {
                   "action_executor":"delay",
                   "executor_property":{
                    "hours":"0",
                    "minutes": "0",
                    "seconds": "5"
                   }
                
                },
                {
                    "action_executor":"dpIssue",
                    "entity_id":"vdevo15725982542****",
                    "executor_property":{
                        "switch_1":true
                    }
                },
              	{
                    "action_executor":"externalAction",
                    "executor_property":{
                    	// Subject to your customization
                    }
                 
                }
            ],
            "automation_id":"p2aWOkEOe2RzA****",
            "background":"https://images.tuyacn.com/smart/rule/cover/bedroom.png",
            "conditions":[
                {
                    "display":{
                        "code":"switch_1",
                        "operator":"==",
                        "value":true
                    },
                    "entity_id":"vdevo15725982542****",
                    "entity_type":1,
                    "order_num":1
                }
            ],
            "enabled": true,
            "status": "1",
            "match_type":1,
            "name":"Automation Test",
        },
        {
            "automation_id":"L07BQVabdqwFP****",
            "background":"https://images.tuyacn.com/smart/rule/cover/house6.png",
            "conditions":[
                {
                    "display":{
                        "code":"battery_percentage",
                        "operator":"<",
                        "value":255
                    },
                    "entity_id":"vdevo156958314001****",
                    "entity_type":1,
                    "order_num":1
                },
                {
                    "display":{
                        "code":"mode",
                        "operator":"==",
                        "value":1
                    },
                    "entity_id":"weqszcaokqlmlkmlcanqklwokl****",
                    "entity_type":15,
                    "order_num":2
                }
            ],
            "enabled": true,
            "match_type":1,
            "name":"Automation Test 1",
        }
    ],
    "success":true,
    "t":1572936751228
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Query an automation scene

API description

Query the specified automation scene of the specified home.

API endpoint

GET /v1.0/homes/{home_id}/automations/{automation_id}

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes
automation_id	String	URI	The ID of the specified automation scene.	Yes

Sample request

GET /v1.0/homes/242****/automations/53IYSXI3gEn2w3Oc

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Result

Parameter	Type	Description
automation_id	String	The ID of the specified automation scene.
name	String	The name of the specified automation scene.
enabled	Boolean	The enabling status.
background	String	The background image.
conditions	List	A list of scene conditions.
preconditions	List	The precondition.
actions	List	A list of actions.
match_type	Integer	Indicates the matching types. Valid values: `1`: Trigger a scene when any condition is met. `2`: Trigger a scene when all conditions are met. `3`: Trigger a scene when the custom conditions are met. Set the logic operation parameter `condition_rule`.
condition_rule	String	The custom condition rule. This parameter is required when the value of `match_type` is `3`. The custom condition rules follow the AND OR formula. Each automation condition is identified by its `order_num`.

Conditions

Parameter	Type	Description	Required
entity_type	Integer	The type of condition. The following condition types are supported: `1`: Trigger by the specified device status. `15`: Trigger by the specified external condition. `3`: Trigger by the specified weather condition. `6`: Trigger by the specified scheduled task.	Yes
display	JSON	Shows the conditions.	Yes
order_num	Integer	The serial number of the specified condition, starting from `1`.	Yes
entity_id	String	The ID of the specified entity that executes the action. Valid values: When the value of `entity_type` is `1`, the value of `entity_id` is the device ID. In this case, this parameter is required. When the value of `entity_type` is `15`, the value of `entity_id` is automatically generated by the system. When the value of `entity_type` is `3`, the value of `entity_id` is the city ID. When the value of `entity_type` is `6`, the value of `entity_id` is `timer`.	No

Display device status conditions

Parameter	Type	Description	Required
code	String	The `statusCode` of the specified device.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The value of the specified code.	Yes

Display external conditions

Parameter	Type	Description	Required
code	String	The key of the specified external condition.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	Object	The code value for the key of the specified external condition.	Yes

Display weather conditions

Parameter	Type	Description	Required
code	String	The key of the specified weather condition. For example, `temp`.	Yes
operator	String	The operator. For more information, see Mapping between code data types and operators.	Yes
value	String	The code value for the key of the specified weather condition.	Yes

Display scheduled task conditions

Parameter	Type	Description	Required
date	String	The date when a scheduled task is triggered, in the format of `yyyyMMdd`. For example, `20191125`.	Yes
loops	String	A seven-digit number consisting of `0` and `1`. `0` means disabled and `1` means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
time	String	The trigger time in the format of 24-hour time. For example, `14:00`.	Yes
timezone_id	String	The time zone ID. Fo example, `Asia/Shanghai`.	Yes

Description of preconditions

The preconditions. You can set the specified time period as a precondition.

Parameter	Type	Description	Required
cond_type	String	Currently, you can only set the specified time period as a precondition. Valid value: `timeCheck`.	Yes
display	JSON	Shows the conditions.	Yes

Description of display in preconditions

Parameter	Type	Description	Required
start	String	The start time in the format of 24-hour time. The default value is a time point of the day. For example, `10:00`.	Yes
end	String	The end time in the format of 24-hour time. For example, `22:00`.	Yes
loops	String	A seven-digit number consisting of `0` and `1`. `0` means disabled and `1` means enabled. The first digit represents Sunday and the other digits represent Monday to Saturday sequentially. For example, `0011000` represents a scheduled task is executed every Tuesday and Wednesday.	Yes
timezone_id	String	The time zone ID. Fo example, `Asia/Shanghai`.	Yes

Description of devices involved in actions

Parameter	Type	Description	Required
entity_id	String	The device ID.	Yes
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: `dpIssue`.	Yes

Description of external actions

Parameter	Type	Description	Required
executor_property	JSON	A custom external action.	Yes
action_executor	String	The type of action. Valid value: `externalAction`.	Yes

Mapping between code data types and operators

type	operator
Boolean	“==”
Integer	“>”,“==”,“<”
Enum	“==”

Sample response on success

{
    "result":[{
            "actions":[
                {
                   "action_executor":"delay",
                   "executor_property":{
                    "hours":"0",
                    "minutes": "0",
                    "seconds": "5"
                   }
                
                },
                {
                    "action_executor":"dpIssue",
                    "entity_id":"vdevo15725982542****",
                    "executor_property":{
                        "switch_1":true
                    }
                },
                {
                    "action_executor":"externalAction",
                    "executor_property":{
                        // Subject to your customization
                    }
                 
                }
            ],
            "automation_id":"p2aWOkEOe2RzA****",
            "background":"https://images.tuyacn.com/smart/rule/cover/bedroom.png",
            "conditions":[
                {
                    "display":{
                        "code":"switch_1",
                        "operator":"==",
                        "value":true
                    },
                    "entity_id":"vdevo15725982542****",
                    "entity_type":1,
                    "order_num":1
                }
            ],
            "enabled": true,
            "match_type":1,
            "name":"Automation Test",
        },
        {
            "automation_id":"L07BQVabdqwFP****",
            "background":"https://images.tuyacn.com/smart/rule/cover/house6.png",
            "conditions":[
                {
                    "display":{
                        "code":"battery_percentage",
                        "operator":"<",
                        "value":255
                    },
                    "entity_id":"vdevo156958314001****",
                    "entity_type":1,
                    "order_num":1
                },
                {
                    "display":{
                        "code":"mode",
                        "operator":"==",
                        "value":1
                    },
                    "entity_id":"weqszcaokqlmlkmlcanqklwokl****",
                    "entity_type":15,
                    "order_num":2
                }
            ],
            "enabled": true,
            "match_type":1,
            "name":"Automation Test 1",
        },
    "success":true,
    "t":1572936751228
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Query external conditions triggering an automation scene

API description

Query external conditions triggering an automation scene in the specified home.

API endpoint

POST /v1.0/homes/{home_id}/automations/{automation_id}/conditions/trigger

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes
automation_id	String	URI	The ID of the specified automation scene.	Yes
conditions	List	Body	The list of scene conditions.	Yes

Conditions

Parameter	Type	Description	Required
entity_id	String	The ID of the specified external condition.	Yes
display	JSON	The condition that triggers an automation scene.	Yes

Display

Parameter	Type	Description	Required
code	String	The `statusCode` of the specified device.	Yes
value	String	The value of the specified code.	Yes

Sample request

POST /v1.0/homes/242****/automations/53IYSXI3gEn2w3Oc/conditions/trigger


[{
	"entity_id":"c9a5a524-d973-4b59-9390-0dcda0f1****",
	"display":{
		"code":"test",
		"value":"test"
	}
}]

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	String	Indicates whether the scene is triggered successfully. `true` is returned when the operation is successful.

Sample response on success

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

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Query devices that support an automation scene

API description

Query a list of devices that support the specified automation scene in the specified home.

API endpoint

GET /v1.0/homes/{home_id}/automation/devices

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	URI	The ID of the user’s home.	Yes
type	String	URL	The supported type. Valid values: `condition`: condition type. `action`: action type.	No

If the type parameter is not output, all devices that support automation scenes will be returned.

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	List	The returned result.

Result

Parameter	Type	Description
device_id	String	The device ID.
uuid	String	The universally unique identifier (UUID) of the specified device.
name	String	The name.
home_id	String	The home ID.
product_id	String	The product ID.

Sample request

GET /v1.0/homes/242****/automation/devices?type=condition

Sample response on success

{
    "result":[
    	{
    		"id":"vedo123****",
    		"uuid":"asdfghnbvcx****",
        "name":"Test Device",
    		"product_id":"r4567543****",
    		"home_id":"242****"
    	}
    ],
    "success":true,
    "t":1572936751228
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Query weather conditions supported by an automation scene

API description

Query various weather conditions supported by the specified automation scene.

API endpoint

GET /v1.0/homes/automation/weather/conditions

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	List	The returned result.

Result

Parameter	Type	Description
category	String	The category.
category_name	String	The name of the specified category.
operators	String	The operator.
property	JSON	The property of the specified category.

Sample request

GET /v1.0/homes/automation/weather/conditions

Sample response on success

{
    "result":[
    		{
    			"category":"temp",
    			"category_name":"Temperature",
    			"operators":"[\"<\",\"==\",\">\"]",
    			"property":{
                    "unit": "℃",
                    "min": -40,
                    "max": 40,
                    "step": 1,
                    "type": "value"
                },
    		}
    ],
    "success":true,
    "t":1572936751228
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Get supported linkage conditions

API description

Get the standard data points of linkage conditions or execution actions based on the home ID.

API endpoint

GET /v1.0/homes/{home_id}/enable-linkage/codes

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	String	URI	The home ID.	Yes

Sample request

GET /v1.0/homes/5232322/enable-linkage/codes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	List	The returned result.

Result

Parameter	Type	Description
device_id	String	The ID of the specified automation device.
functions	List	The operation that is performed.
status	List	The trigger condition of the specified operation.

Functions

Parameter	Type	Description
code	String	The code of the standard data point sent from the cloud to a device.
name	String	The code name.
type	String	The type of data sent from the cloud to a device. The following data types are supported: Boolean Integer Enum
values	JSON	The value range of the specified code.

Status

Parameter	Type	Description
code	String	The code of a standard status reported by a device to the cloud.
name	String	The code name.
type	String	The type of data reported to the cloud. The following data types are supported: Boolean Integer Enum
values	JSON	The value range of the specified code.

Sample response on success

{
    "success": true,
    "t": 1541072348540,
    "result": [
                {
                  "device_id": "0120090568c63a89****",
                  "functions": [
                      {
                          "name": "Brightness",
                          "code": "bright_value",
                          "type": "Integer",
                          "values": {
                                        "max":255,
                                        "min":25,
                                        "scale":0,
                                        "step":1,
                                        "type":"value",
                                        "unit":""
                                    }
                      },
                      {
                        "name": "Switch",
                        "code": "switch_led",
                        "type": "Boolean"
                    }
                  ],
                  "status": [
                      {
                        "name": "Mode",
                          "code": "work_mode",
                          "type": "Enum",
                          "values":  {
                                        "range": [
                                                    "white",
                                                    "colour",
                                                    "scene",
                                                    "scene_1",
                                                    "scene_2",
                                                    "scene_3",
                                                    "scene_4"
                                                ],
                                         "type": "Enum"
                                    }
                      }
                  ]
                }
            ]
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Get supported linkage conditions

API description

Get the standard data points of linkage conditions or execution actions based on the device ID.

API endpoint

GET /v1.0/devices/{device_id}/enable-linkage/codes

Request parameters

Parameter	Type	Parameter type	Description	Required
device_id	String	URI	The device ID.	Yes

Sample request

GET /v1.0/devices/0120090568c63a89cb34/enable-linkage/codes

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Result

Parameter	Type	Description
device_id	String	The device ID.
functions	List	The standard instruction for performing actions.
status	List	The standard status that triggers an action.

Functions

Parameter	Type	Description
code	String	The code of the standard data point sent from the cloud to a device.
name	String	The code name.
type	String	The type of data sent to a device. The following data types are supported: Boolean Integer Enum
values	JSON	The value range of the specified code.

Status

Parameter	Type	Description
code	String	The code of a standard status reported by a device to the cloud.
name	String	The code name.
type	String	The type of data reported to the cloud. The following data types are supported: Boolean Integer Enum
values	JSON	The value range of the specified code.

Sample response on success

{
    "success": true,
    "t": 1541072348540,
    "result": {
                  "device_id": "0120090568c63a89****",
                  "functions": [
                      {
                          "name": "Brightness",
                          "code": "bright_value",
                          "type": "Integer",
                          "values": {
                                        "max":255,
                                        "min":25,
                                        "scale":0,
                                        "step":1,
                                        "type":"Integer",
                                        "unit":""
                                    }
                      },
                      {
                        "name": "Switch",
                        "code": "switch_led",
                        "type": "Boolean",
                        "values": {
                                    "type": "Boolean"
                                  }
                    }
                  ],
                  "status": [
                      {
                          "name": "Mode",
                          "code": "work_mode",
                          "type": "Enum",
                          "values":  {
                                        "range": [
                                                    "white",
                                                    "colour",
                                                    "scene",
                                                    "scene_1",
                                                    "scene_2",
                                                    "scene_3",
                                                    "scene_4"
                                                ],
                                         "type": "Enum"
                                    }
                      }
                  ]
            }
}

Sample response on failure

{
    "success": false,
    "code": 1100,
    "msg": "param is empty",
    "t": 1540954683193
}

Enable an automation scene

API description

Enable the specified automation scene.

API endpoint

PUT /v1.0/homes/{home_id}/automations/{automation_id}/actions/enable

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	The home ID.	URI	Yes
automation_id	String	The ID of the specified automation scene.	URI	Yes

Return parameters:

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The 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.

Sample request

PUT /v1.0/homes/242****/automations/53IYSXI3gEn2w3Oc/actions/enable

Sample response

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

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.

Disable an automation scene

API description

Disable the specified automation scene.

API endpoint

PUT /v1.0/homes/{home_id}/automations/{automation_id}/actions/disable

Request parameters

Parameter	Type	Parameter type	Description	Required
home_id	Long	The home ID.	URI	Yes
automation_id	String	The ID of the specified automation scene.	URI	Yes

Return parameters:

Parameter	Type	Description
code	Integer	The response code. For more information, see Global Error Codes.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: success. `false`: failure.
msg	String	The 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.

Sample request

PUT /v1.0/homes/242****/automations/53IYSXI3gEn2w3Oc/actions/disable

Sample response

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

Error codes

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

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

Prev DocDevice Timing Management

Next DocIndustrial Scenarios