Smart Scene

Last Updated on : 2021-09-18 08:24:00download

This topic describes the API operations that are used to configure space scenes.

API operation

Request method	API endpoint	Description
GET	/v1.0/illumination/smart/scene/list	The list of scenes
GET	/v1.0/illumination/smart/scene/{id}	Query the scene details
POST	/v1.0/illumination/smart/scene/add	Create a scene
POST	/v1.0/illumination/smart/scene/update	Update a scene
GET	/v1.0/illumination/smart/scene/action/property	Query the data of the execution action

The list of scenes

API description

Get a list of scenes in the space under a specified project.

API endpoint

GET /v1.0/illumination/smart/scene/list

Request parameter

Name	Type	Location	Description	Required
projectId	String	body	The project ID.	Yes
roomIds	List	body	The list of space IDs.	No

Return parameter

Name	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicate whether the operation succeeds. `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The request result.

Description of result

[
  {
    "ruleId": "String // The ruleId of the smart linkage. The value is used during updating",
    "name": "String // The name",
    "projectId": "String // The project ID",
    "background": "String // The background image",
    "displayIcon": "String // The icon to be displayed on the homepage",
    "displayColor": "String // The color",
    "actions": [
      {
        "id": "String // The action ID of the smart linkage. The value is used during updating",
        "entityId": "String // The ID of the execution object",
        "entityName": "String // The name of the execution object",
        "executorProperty": {},
        "actionExecutor": "String // The property of the execution action",
        "actionDisplay": "String // The description of the execution action",
        "extraProperty": {},
        "actionDisplayNew": {},
        "executorType": "int // The execution type. `1`: Send a data point (DP). `3`: Send a device group DP. `4`: The scene is triggered as an action. `5`: Delay an action. `6`: The automation action is enabled. `7`: The automation action is disabled",
        "iconUrl": "String // The URL address of the icon",
        "productId": "String // The product ID",
        "orderNum": "int // The sequence code"
      }
    ],
    "extendInfo": "String // Extended information",
    "type": "int // The smart linkage types. 1:\"Timing\",2:\"Scene\",3: Automation\"",
    "roomId": "String // The room ID",
    "deviceIds": "String[] // The ID set of a single device in a scene",
  }
]

Sample request

{
  "roomIds": "",
  "projectId": ""
}

Sample response

{
    "actions":[
        {
            "actionDisplayNew":{
                "1":[
                    "Switch",
                    "On"
                ]
            },
            "actionExecutor":"commerceLightDpIssue",
            "entityId":"1367290337185304576",
            "entityName":"autoTest_pkg_G_WIFI_24",
            "executorProperty":{
                "led_switch":true
            },
            "executorType":3,
            "extraProperty":{
                "roomName":"AutoTest_VirtualDevices"
            },
            "productId":"qadpdqfc0kkklov3"
        }
    ],
    "background":"https://images.tuyacn.com/smart/rule/cover/evening.png",
    "conditions":[
        {
            "entityId":"tuyadae641eb825d9db7",
            "entitySubIds":"101",
            "entityType":1,
            "expr":[
                [
                    "$dp101",
                    "==",
                    true
                ]
            ],
            "extraInfo":{
                "areaId":19797715
            }
        }
    ],
    "matchType":1,
    "name":"autoTest_Linkage19222",
    "preConditions":[
 
   ],
    "projectId":"1329400489246232576",
    "type":3
}

Query the scene details

API description

Query the details of one scene by the scene ID.

API endpoint

GET /v1.0/illumination/smart/scene/{id}

Request parameter

Name	Type	Location	Description	Required
id	String	url	The scene ID	Yes

Return parameter

Name	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicate whether the operation succeeds. `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The request result.

Description of result

For more information about the result parameter, see the List of scenes.

Sample response

For more information about the sample response, see the List of scenes.

Create a scene

API description

Create a scene.

API endpoint

POST /v1.0/illumination/smart/scene/add

Request parameter

Name	Type	Location	Description	Required
ruleId	String	body	The `ruleId` of the smart linkage. The value is used during updating.	No
name	String	body	The name of the scene.	Yes
projectId	String	body	The project ID.	Yes
background	String	body	The background image.	No
displayIcon	String	body	The icon displayed on the homepage.	No
displayColor	String	body	The color.	No
actions.id	String	body	The action ID of the smart linkage. The value is used during updating.	No
actions.entityId	String	body	The ID of the execution object.	Yes
actions.entityName	String	body	The name of the execution object.	Yes
actions.executorProperty	Object	body	The property of the execution action.	Yes
actions.actionExecutor	String	body	The property of the execution action.	Yes
actions.extraProperty	Object	body	The additional information.	No
actions.actionDisplayNew	Object	body	Description of the DP actions.	No
actions.executorType	int	body	The execution type. `1`: Send a DP. `3`: Send a group DP. `4`: The scene is triggered as an action. `5`: Delay an action. `6`: The automation action is enabled. `7`: The automation action is disabled.	No
actions.iconUrl	String	body	The URL address of the icon.	No
actions.productId	String	body	The product ID.	No
actions.orderNum	int	body	The sequence code.	No
extendInfo	String	body	The extension information.	No
type	int	body	The type of smart linkage. `1`: Timing `2`: Scene `3`: Automation	No
roomId	String	body	The room ID.	Yes

Return parameter

Name	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicate whether the operation succeeds. `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The request result.

Description of result

{
    "ruleId": "String // The ruleId of the smart linkage. The value is used during updating",
    "name": "String // The name",
    "projectId": "String // The project ID",
    "background": "String // The background image",
    "displayIcon": "String // The icon to be displayed on the homepage",
    "displayColor": "String // The color",
    "actions": [
      {
        "id": "String // The action ID of the smart linkage. The value is used during updating",
        "entityId": "String // The ID of the execution object",
        "entityName": "String // The name of the execution object",
        "executorProperty": {},
        "actionExecutor": "String // The property of the execution action",
        "actionDisplay": "String // The description of the execution action",
        "extraProperty": {},
        "actionDisplayNew": {},
        "executorType": "int // The execution type. `1`: Send a data point (DP). `3`: Send a device group DP. `4`: The scene is triggered as an action. `5`: Delay an action. `6`: The automation action is enabled. `7`: The automation action is disabled",
        "iconUrl": "String // The URL address of the icon",
        "productId": "String // The product ID",
        "orderNum": "int // The sequence code"
      }
    ],
    "extendInfo": "String // Extended information",
    "type": "int // The smart linkage types. 1:\"Timing\",2:\"Scene\",3: Automation\"",
    "roomId": "String // The room ID",
    "deviceIds": "String[] // The ID set of a single device in a scene",
}

Sample request

{
    "actions":[
        {
            "actionDisplayNew":{
                "1":[
                    "Switch",
                    "Off"
                ]
            },
            "actionExecutor":"dpIssue",
            "entityId":"6cbf5559a8f6ab224evayv",
            "entityName":"Wifi",
            "executorProperty":{
                "1":true
            },
            "executorType":1,
            "extraProperty":{
                "roomName":"AutoTest_VirtualDevices"
            },
            "iconUrl":"https://images.tuyacn.com/smart/icon/ay1528439289656kE9yz/68c5be5e667596b6c1b033559868f2bd.png",
            "productId":"qadpdqfc0kkklov3"
        }
    ],
    "areaId":"19797715",
    "name":"autoTest_Scene20464",
    "projectId":"1329400489246232576",
    "roomId":"1349285973837565952",
    "type":2
}

Sample response

{
    "actions":[
        {
            "actionDisplayNew":{
                "1":[
                    "Switch",
                    "Off"
                ]
            },
            "actionExecutor":"dpIssue",
            "entityId":"6cbf5559a8f6ab224evayv",
            "entityName":"Wifi",
            "executorProperty":{
                "1":true
            },
            "executorType":1,
            "extraProperty":{
                "roomName":"AutoTest_VirtualDevices"
            },
            "productId":"qadpdqfc0kkklov3"
        }
    ],
    "name":"autoTest_Scene20464",
    "projectId":"1329400489246232576",
    "roomId":"1349285973837565952",
    "type":2,
    "ruleId":"FmMICDM7JtFuUIBC"
}

Update a scene

API description

Update a scene.

API endpoint

POST /v1.0/illumination/smart/scene/update

Request parameter

Name	Type	Location	Description	Required
ruleId	String	body	The `ruleId` of the smart linkage, which is used during updating.	No
name	String	body	The name of the scene.	Yes
projectId	String	body	The project ID.	Yes
background	String	body	The background image.	No
displayIcon	String	body	The icon displayed on the homepage.	No
displayColor	String	body	The color.	No
actions.id	String	body	The action ID of the smart linkage. The value is used during updating.	No
actions.entityId	String	body	The ID of the execution object.	Yes
actions.entityName	String	body	The name of the execution object.	Yes
actions.executorProperty	Object	body	The property of the execution action.	Yes
actions.actionExecutor	String	body	The property of the execution action.	Yes
actions.extraProperty	Object	body	The additional information.	No
actions.actionDisplayNew	Object	body	actionDisplayNew	No
actions.executorType	int	body	The execution type. `1`: Send a DP. `3`: Send a group DP. `4`: The scene is triggered as an action. `5`: Delay an action. `6`: The automation action is enabled. `7`: The automation action is disabled.	No
actions.iconUrl	String	body	iconUrl	No
actions.productId	String	body	The product ID.	No
actions.orderNum	int	body	The sequence code.	No
extendInfo	String	body	The extension information.	No
type	int	body	The type of smart linkage. `1`: Timing `2`: Scene `3`: Automation	No
roomId	String	body	The room ID.	Yes
areaId	String	body	The room ID (on the app).	Yes
deviceIds	String[]	body	The ID set of a single device in a scene.	No

Return parameter

Name	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicate whether the operation succeeds. `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The request result.

Description of result

For more information about the result parameter, see Create a scene.

Sample request

For more information about the sample request, see Create a scene.

Sample response

For more information about the sample response, see Create a scene.

Query the data of the execution action

API description

Query the data of the execution action.

API endpoint

GET /v1.0/illumination/smart/scene/action/property

Request parameter

Name	Type	Location	Description	Required
deviceType	String	body	The device types. `dgzm`: electrical and lighting products `zm`: lighting `djd`: major appliances `xjd`: small appliances `cfdq`: kitchen appliances `jjaf`: home security `hjjk`: exercise and health `sxj`: video surveillance `wgzk`: gateway control `jnny`: energy `jyyl`: digital entertainment `gny`: industry and agriculture `qt`: other	No
roomId	String	body	The room ID.	No

Return parameter

Name	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty when the operation succeeded.
success	Boolean	Indicate whether the operation succeeds. `true`: succeeded. `false`: failed.
msg	String	The error message that is returned if the request fails. It is empty if the request is successful.
t	Long	The returned 13-bit timestamp.
result	Object	The request result.

Sample request

{
  "deviceType": "zm"
}

Sample response

[{
 	"dataPoints": [{
 		"defaultValue": true,
 		"dpCode": "switch_led",
 		"dpId": 20,
        "dpName": "Switch",
        "dpProperty": "{\"type\":\"bool\"}",
        "editable": true,
        "valueRangeJson": [
            [true, "On"],
            [false, "Off"]
        ]
    }],
    "functionName": "Switch",
    "functionType": 0,
    "productId": "nspmvtve8q1gey4o"
}, {
 	"dataPoints": [{
       "defaultValue": "white",
       "dpCode": "work_mode",
       "dpId": 21,
       "dpName": "Mode",
       "dpProperty": "{\"range\":[\"white\",\"colour\",\"scene\",\"music\"],\"type\":\"enum\"}",
       "editable": true,
       "valueRangeJson": [
           ["white", "white light"],
           ["colour", "colored light"],
           ["scene", "scene"],
           ["music", "music"]
        ]
    }],
    "functionName": "Mode",
    "functionType": 0,
    "productId": "nspmvtve8q1gey4o"
}, {
	"dataPoints": [{
		"defaultValue": "10",
		"dpCode": "bright_value",
		"dpId": 22,
		"dpName": "Brightness value",
		"dpProperty": "{\"unit\":\"\",\"min\":10,\"max\":1000,\"scale\":0,\"step\":1,\"type\":\"value\"}",
		"editable": true
	}],
	"functionName": "Brightness value",
	"functionType": 0,
	"productId": "nspmvtve8q1gey4o"
}, {
	"dataPoints": [{
		"defaultValue": "0",
		"dpCode": "countdown",
		"dpId": 26,
		"dpName": "The remaining time of the countdown",
		"dpProperty": "{\"unit\":\"second\",\"min\":0,\"max\":86400,\"scale\":0,\"step\":1,\"type\":\"value\"}",
		"editable": true
	}],
	"functionName": "The remaining time of the countdown",
	"functionType": 0,
	"productId": "nspmvtve8q1gey4o"
}]

Error code

The following table describes common error codes for this API. For more information, see Error Code.

Error code	Description
500	The error message is returned because a system error has occurred.
1106	The error message is returned because you are not authorized to make the API request.

Prev DocSmart Rules

Next DocSmart Linkage