Custom Template of Scene Linkage

Last Updated on : 2024-06-20 06:21:22download

The custom template system allows users to generate smart scenes and linkages for multiple spaces in the same task.

The system selection pool provides a series of dimensions for users to accurately select the devices and groups required in the space and build smart scene linkage. You can also select sub-scene and linkage to form a more complex scene linkage.

Regarding SaaS solutions, the system builds and opens up more advanced office industry templates, education industry templates, rhythm templates, and program templates based on custom templates. These higher-level templates will be assembled into multiple well-designed custom templates.

Attributes supported by the system selection pool

Custom Template of Scene Linkage

Request method	API	Description
GET	/v1.0/iot-02/smart/support-selector	Get the selection attributes supported by the system.
GET	/v1.0/iot-02/smart/template-list	Get the template list.
GET	/v1.0/iot-02/smart/template/{id}	Get a template by template ID.
POST	/v1.0/iot-02/smart/template/simple-create	Create simple custom templates.
POST	/v1.0/iot-02/smart/template/create	Create general custom templates.
POST	/v1.0/iot-02/smart/template/senior-create	Create advanced custom templates.
POST	/v1.0/iot-02/smart/template/remove/{id}	Delete custom templates.
POST	/v1.0/iot-02/smart/template/generate/{id}	Apply templates.

Get the selection attributes supported by the system

API description

Get the selection attributes supported by the system, related to the products in the product library.

These attributes can be used as some options for creating templates. This API is optional and can be used as a model reference for creating templates.

API endpoint

GET /v1.0/iot-02/smart/support-selector

Request parameter

Parameter	Type	Parameter type	Description	Required
pid	String	body	The product ID (PID).	No
topCategory	String	body	The level-1 category.	No
roomId	String	body	The area ID.	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of the result parameter

{
  "product": [// Product category
    {
      "code": "String // The attribute code",
      "name": "String // The attribute name"
    }
  ],
  "topCategory": [// The level-1 category
    {
      "code": "String // The attribute code",
      "name": "String // The attribute name"
    }
  ],
  "secondCategory": [// The level-2 category
    {
      "code": "String // The attribute code",
      "name": "String // The attribute name"
    }
  ],
  "thirdCategory": [// The level-3 category
    {
      "code": "String // The attribute code",
      "name": "String // The attribute name"
    }
  ],
  "purpose": [// Device purpose
    {
      "code": "String // The attribute code",
      "name": "String // The attribute name"
    }
  ]
}

Sample request

{
  "topCategory": "The level-1 category",
  "pid": "The product ID",
  "roomId": "The area ID",
}

Sample response

{
    "result": {
        "product": [
            {
                "code": "pbkktyh5i59sj6nm",
                "name": "A60 RGB+CCT WIFI+Bluetooth"
            },
            {
                "code": "sosdczdl",
                "name": "RGBCW"
            }
        ],
        "secondCategory": [
            {
                "code": "dj",
                "name": "Light source"
            }
        ],
        "thirdCategory": [
            {
                "code": "wf_ble_dj",
                "name": "Wi-Fi_Bluetooth LE lighting"
            },
            {
                "code": "zig_dj",
                "name": "Zigbee lighting"
            }
        ],
        "topCategory": [
            {
                "code": "zm",
                "name":"Lighting"
            }
        ]
    },
    "success": true,
    "t": 1629976090010
}

Get template list

API description

Get a list of user-created templates, including user-created and system built-in templates.

API endpoint

GET /v1.0/iot-02/smart/template-list

Request parameter

Parameter	Type	Parameter type	Description	Required
page	int	body	The page number.	No
pageSize	int	body	The number of entries returned per page.	No
templateName	String	body	The name of a template.	No
templateType	int	body	1. Scene template 2. Schedule template 3. Linkage template	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of the result parameter

{
  "templateId": "String // The template ID",
  "templateName": "String // The template name",
  "templateLabel": "String // The template label",
  "templateType": "int // The template type. 1: Scene template. 2: Schedule template. 3: Linkage template",
  "category": "String // The template category",
  "preConditionExpr": "String // The precondition expression",
  "extendInfo": "String // The extended information",
  "userNum": "int // The number of template uses",
  "matchType": "int // 1:Triggered by any condition. 2: Triggered when all conditions are met.",
  "ranking": "int // The ranking",
   "remark": "String // Remarks",
  "configs": [
    {
      "selector": "String // The selector",
      "selectorType": "int // The type of selector. 1: Device selector. 2: Group selector. 3: Scene selector. 4: Automation selector",
      "strategyExpr": "String // The strategy expression",
      "strategyType": "int // The strategy type"
    }
  ]
}

Sample request

{
    "page":1,
    "pageSize":10,
    "templateName":"xxx"
}

Sample response

{
    "result": {
        "current": 1,
        "hitCount": false,
        "optimizeCountSql": true,
        "orders": [],
        "pages": 0,
        "records": [
            {
                "category": "",
                "extendInfo": "",
                "matchType": 0,
                "preConditionExpr": "",
                "ranking": 0,
                "remark": "",
                "templateId": "1432526379668254720",
                "templateLabel": "",
                "templateName": "New Scene Template 1",
                "templateType": 1,
                "userNum": 0
            }
        ],
        "searchCount": true,
        "size": 10,
        "total": 0
    },
    "success": true,
    "t": 1630555370694
}

Get template by template ID

API description

Get the details of a specified template by template ID.

API endpoint

GET /v1.0/iot-02/smart/template/{id}

Request parameter

Parameter	Type	Parameter type	Description	Required
id	String	url	Add comments.	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of the result parameter

The same as the API of getting the template list.

Create simple custom templates

API description

Create a simple custom template, which is used to generate scenes and match rules for a single group.

API endpoint

POST /v1.0/iot-02/smart/template/simple-create

Request parameter

Parameter	Type	Parameter type	Description	Required
templateName	String	body	The name of a template.	Yes
templateLabel	String	body	The label of a template.	No
remark	String	body	The remarks of a template.	No
rule.name	String	body	The rule name.	No
rule.pid	String	body	The product ID (PID).	No
rule.thirdCategory	String	body	The level-3 category.	No
rule.dps	Object	body	The action DP. It is a key-value pair in the format of `dpCode:dpValue`.	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Sample request

{
	"templateName": "Test Scene Template",
  "rule":{
      "name":"RGBCW",
      "pid":"sosdczdl",
      "dps":{"swith_led":true}
  }
}

Sample response

{
    "result": "1433683021394890752",// The template ID
    "success": true,
    "t": 1630651643529
}

Create general custom templates

API description

Create a general custom template, which is used to generate scenes and match rules for multiple groups. The object can be one device and groups, including delayed actions.

API endpoint

POST /v1.0/iot-02/smart/template/create

Request parameter

Parameter	Type	Parameter type	Description	Required
templateName	String	body	The name of a template.	Yes
templateLabel	String	body	The label of a template.	No
remark	String	body	The remarks of a template.	No
deviceRules.name	String	body	The rule name.	No
deviceRules.pid	String	body	The product ID (PID).	No
deviceRules.thirdCategory	String	body	The level-3 category.	No
deviceRules.topCategory	String	body	The level-1 category.	No
deviceRules.secondCategory	String	body	The level-2 category.	No
deviceRules.devicePurpose	String	body	The device purpose.	No
deviceRules.dps	Object	body	The action DP. It is a key-value pair in the format of `dpCode:dpValue`.	No
deviceRules.anyMatch	Boolean	body	Indicates whether to match any of the device purposes, device names, and device categories.	No
deviceRules.nextActionDelayTime	int	body	The delay of the next action in seconds.	No
groupRules.name	String	body	The rule name.	No
groupRules.pid	String	body	The product ID (PID).	No
groupRules.thirdCategory	String	body	The level-3 category.	No
groupRules.dps	Object	body	The action DP. It is a key-value pair in the format of `dpCode:dpValue`.	No
groupRules.nextActionDelayTime	int	body	The delay of the next action in seconds.	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Sample request

{
	"templateName": "Test Scene Template 1",
	"templateType": 1,
  "deviceRules":[{
  	"name":"RGBCW",
  	"pid":"sosdczdl",
  	"dps":{"swith_led":true},
  	"devicePurpose":"office"
  	"nextActionDelayTime":30
  }],
  "groupRules":[{
  	"name":"RGBCW",
  	"pid":"sosdczdl",
  	"dps":{"swith_led":true},
  	"nextActionDelayTime":30
  }]
}

Sample response

{
    "result": "1433683021394890752",// The template ID
    "success": true,
    "t": 1630651643529
}

Create advanced custom templates

API description

Create an advanced custom template, which is used to generate scenes, schedule, and linkage.

The execution rules include a single device, group, scene trigger, automatic start and stop, and delayed action.
The trigger rules include device actions, timing rules, sunrise and sunset rules.

API endpoint

POST /v1.0/iot-02/smart/template/senior-create

Request parameter

Many optional parameters are available. You can consult Tuya staff about how to meet your needs with a few parameters.

Parameter	Type	Parameter type	Description	Required
templateName	String	body	The name of a template.	Yes
templateLabel	String	body	The label of a template.	No
templateType	int	body	1. Scene template 2. Schedule template 3. Linkage template	No
remark	String	body	The remarks of a template.	No
validityPeriod	String	body	Indicates effective dates from Sunday to Sunday. For example, `0001100` indicates every Wednesday and Thursday.	No
matchType	int	body	`1`: Trigger when any condition is met. `2`: Trigger when all conditions are met.	No
deviceRules.name	String	body	The rule name.	No
deviceRules.pid	String	body	The product ID (PID).	No
deviceRules.thirdCategory	String	body	The level-3 category.	No
deviceRules.topCategory	String	body	The level-1 category.	No
deviceRules.secondCategory	String	body	The level-2 category.	No
deviceRules.devicePurpose	String	body	The device purpose.	No
deviceRules.dps	Object	body	The action DP. It is a key-value pair in the format of `dpCode:dpValue`.	No
deviceRules.anyMatch	Boolean	body	Indicates whether to match any of the device purpose, device name, and device category.	No
deviceRules.nextActionDelayTime	int	body	The delay of the next action in seconds.	No
groupRules.name	String	body	The rule name.	No
groupRules.pid	String	body	The product ID (PID).	No
groupRules.thirdCategory	String	body	The level-3 category.	No
groupRules.dps	Object	body	The action DP. It is a key-value pair in the format of `dpCode:dpValue`.	No
groupRules.nextActionDelayTime	int	body	The delay of the next action in seconds.	No
sceneRules.templateId	String	body	The template used by the scene.	No
sceneRules.name	String	body	The scene name.	No
sceneRules.nextActionDelayTime	int	body	The delay of the next action in seconds.	No
linkageRules.templateId	String	body	The template used by the automation.	No
linkageRules.name	String	body	The name of a specified automation.	No
linkageRules.executeType	int	body	`1`: start. `2`: stop.	No
deviceConditionRule.name	String	body	The rule name.	No
deviceConditionRule.pid	String	body	The product ID (PID).	No
deviceConditionRule.thirdCategory	String	body	The level-3 category.	No
deviceConditionRule.exprs.dpId	String	body	The ID of a data point (DP).	No
deviceConditionRule.exprs.operator	String	body	The operators, including equal to `==`, greater than `>`, and less than `<`.	No
deviceConditionRule.exprs.dpValue	Object	body	The value of a DP.	No
timerRule.loops	String	body	The cycle, which is marked in the order of 7123456. For example, `0001100` indicates every Wednesday and Thursday.	No
timerRule.timezoneId	String	body	The time zone.	No
timerRule.time	String	body	The time in the format of `HH:mm`.	No
timerRule.date	String	body	The date in the format of `yyyymmdd`.	No
envRule.sunsetrise	String	body	`sunrise`: triggered by the sunrise. `sunset`: triggered by the sunset.	No
envRule.cityId	String	body	The ID of a city that triggers a template.	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Sample request

{
	  "templateName": "Advanced Scene Template",
	  "templateType": 1,
    "validityPeriod": "0001100",
    "matchType":1,
    "deviceRules":[{
        "name":"RGBCW",
        "pid":"sosdczdl",
        "devicePurpose":"office",
        "dps":{"swith_led":true}
    }],
    "groupRules":[{
        "name":"RGBCW",
        "pid":"sosdczdl",
        "dps":{"swith_led":true}
    }],
    "conditionRule":{
        "name":"RGBCW",
        "pid":"sosdczdl",
        "exprs":[{
            "dpId":"1",
            "operator":"==",
            "dpValue":"true"
        }]
    },
    "timerRule":{

    }
}

Sample response

{
    "result": "1433683021394890752",// The template ID
    "success": true,
    "t": 1630651643529
}

Delete custom templates

API description

A user deletes the template he/she created.

API endpoint

POST /v1.0/iot-02/smart/template/remove/{id}

Request parameter

Parameter	Type	Parameter type	Description	Required
id	String	url	Add comments.	false

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of the result parameter

true/false

Sample request

{
  "id": "1433683021394890752"
}

Apply templates

API description

Apply a template to a specific space to generate scene and schedule linkage.

API endpoint

POST /v1.0/iot-02/smart/template/generate/{id}

Request parameter

Parameter	Type	Parameter type	Description	Required
roomId	String	body	Add comments.	No
id	String	url	Add comments.	No

Return parameter

Parameter	Type	Description
code	Integer	The error code. For more information, see the error code section. It is null when the operation succeeded.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request fails. It will return null if the request succeeds.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of the result parameter

The ID of the generated scene linkage.

Sample request

{
  "roomId": ""
}

Check Matching of Templates and Spaces

API description

Check whether the templates are suitable for the spaces. The matched template can be applied to generate scene linkage.

API endpoint

POST /v1.0/iot-02/smart/template/check

Request parameter

Parameter	Type	Parameter type	Description	Required
templateId	String	body	The template ID.	No
roomIds	List	body	The list of space IDs.	No

Return parameter

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

Description of the result parameter

[{
    "mathType": "0: not match, 1: match, 2: partial match",
    "roomId": "The space ID"
}]

Sample request

{
    "templateId": "1435599419729842176",
    "roomIds": [
        "1291653765719515136"
    ]
}

Sample response

{
    "result": [
        {
            "mathType": 0,
            "roomId": "1291653765719515136"
        }
    ],
    "success": true,
    "t": 1631169202643
}

Error code

The following table lists the common service error codes for this interface. For more error codes, see global error codes.

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

Prev DocSmart Linkage

Next DocTemplate Recommendation