Smart Scene

Last Updated on : 2021-07-26 03:48:19download

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.