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.