Tuya Developer PlatformSmart IndustriesCommercial LightingSmart RulesSmart Linkage

Smart Linkage

Last Updated on : 2023-11-30 10:16:15download

This topic describes how to create, update, query, and remove a smart linkage.

API list

Request method	API endpoint	Description
GET	/v1.0/illumination/smart/linkage(schedule)/list	Query the list of smart linkage
GET	/v1.0/illumination/smart/linkage(schedule)/{id}	Query linkage details
POST	/v1.0/illumination/smart/linkage(schedule)/add	Create a smart linkage
POST	/v1.0/illumination/smart/linkage(schedule)/update	Update a smart linkage
POST	/v1.0/illumination/smart/change-status	Enable or disable a rule
POST	/v1.0/illumination/smart/remove	Remove a linkage rule

Query the list of smart linkage

API description

Get the list of smart linkage under a specified project.

API endpoint

Linkage: GET /v1.0/illumination/smart/linkage/list
Schedule: GET /v1.0/illumination/smart/schedule/list

Request parameters

Parameter name	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	No

Response parameters

Parameter name	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: `true`: succeeded. `false`: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned 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 is enabled as an action. 7. The automation is disabled as an action.",
        "iconUrl": "String //iconUrl",
        "productId": "String // The product ID",
        "orderNum": "int // The sequence code"
      
    ],
    "extendInfo": "String // The extended information",
    "enabled": "boolean // Indicate whether it is enabled",
    "preConditions": [
      {
        "id": "String // The precondition ID. The value is used during updating",
        "condType": "String // The condition type. According to effective time, set to timeCheck for a fixed value",
        "expr": {}
      }
    ],
    "conditions": [
      {
        "id": "String // The condition ID, which is used during updating",
        "entityType": "int // The condition type. 6: Trigger at a specified time. 1: Trigger when the device status is changed",
        "entityId": "String // The ID of the entity that triggers the condition. Enter timer for the timing type",
        "entitySubIds": "String // The subID of the entity that triggers the condition. Enter dpId for a device and timer for the timing type",
        "entityName": "String // The name of the entity that triggers the condition",
        "expr": {},
        "exprDisplay": "String // Display as a conditional expression",
        "orderNum": "int // The sequence",
        "extraInfo": {},
        "iconUrl": "String //iconURL",
        "extra": "String // The additional information",
        "productId": "String // The product ID"
      }
    ],
    "matchType": "int //matchType //  MatchType enumeration. 1: Triggered by any condition. 2: Triggered when all conditions are met
  }
]

Sample request

{
  "projectId": ""
}

Sample response

{
    "actions":[
        {
            "actionDisplayNew":{
                "1":[
                    "Switch",
                    "On"
                ]
            },
            "actionExecutor":"dpIssue",
            "entityId":"6cc5e16f547d3087eas***",
            "entityName":"Staircase ceiling spotlight 2",
            "executorProperty":{
                "1":true
            },
            "executorType":1,
            "extraProperty":{
                "roomName":"Restaurant"
            },
            "iconUrl":"https://images.tuyacn.com/smart/icon/bay1603698514323MDS1/dde808cefa3622daada79f1379833d97.png",
            "productId":"gmlvm***"
        }
    ],
    "conditions":[
        {
            "entityId":"54360746500291caa950",
            "entitySubIds":"1",
            "entityType":1,
            "expr":[
                [
                    "$dp1",
                    "==",
                    true
                ]
            ],
            "extraInfo":{
                "areaId":20696183
            }
        }
    ],
    "matchType":1,
    "name":"On",
    "ruleId":"Gi7c4DG872VE0y7v",
    "preConditions":[
      "expr": {
        "start": "00:00",   
        "end": "23:59",    
        "timeInterval": "allDay",       
        "loops": "1111111",     
        "timeZoneId": "Asia/Shanghai"
      },
      "holiday":{
           "support":true, //true: execute on public holidays, false: not execute on public holidays
           "regionCode":"CHN" // The area code
      },
      "stopDates":[//Disabled time period
      {
          "start":"20230501",
          "end":"20230505"
      },
      {
          "start":"yyyyMMdd",
          "end":"yyyyMMdd"
      }],
      "condType": "timeCheck" // A fixed value
    ],
    "projectId":"1353534067387195392",
    "type":3
}

Query linkage details

API description

Query linkage details by ruleID.

API endpoint

Linkage: GET /v1.0/illumination/smart/linkage/{id}
Schedule: GET /v1.0/illumination/smart/schedule/{id}

Request parameters

Parameter name	Type	Parameter type	Description	Required
id	String	url	The ID of the specified rule.	No

Response parameters

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

Description of result

For more information about the result parameter, see Query the list of smart linkage.

Sample request

{
  "id": ""
}

Sample response

For more information about the sample response, see Query the list of smart linkage.

Create a smart linkage

API description

Create a smart linkage.

API endpoint

Linkage: POST /v1.0/illumination/smart/linkage/add
Schedule: POST /v1.0/illumination/smart/schedule/add

Request parameters

See the following example.

Response parameters

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

Description of result

For more information about the result parameter, see Query the list of smart linkage.

Sample request

{
    "actions":[
        {
            "actionExecutor":"ruleTrigger",
            "entityId":"U295lPyAkJ7pg***",
            "entityName":"Lights off by the window during the day, and 20% brightness for other lights",
            "executorProperty":{},
            "executorType":4,
            "extraProperty":{},
            "iconUrl":"https://images.tuyacn.com/smart/rule/cover/starry.png"
        }
    ],
    "conditions":[
        {
            "entityId":"6c76a35823158ee1f2o***",
            "entityName":"General Manager Office 1 Entry",
            "entitySubIds":"1",
            "entityType":1,
            "expr":[
                [
                    "$dp1",
                    "==",
                    "active"
                ]
            ],
            "exprDisplay":"Working status: active",
            "extraInfo":{},
            "iconUrl":"https://images.tuyacn.com/smart/icon/ay1557398960654g7n7N/304318735defedab0c6ec0f5016942f8.jpg",
            "productId":"lgstepha"
        }
    ],
    "enabled":true,
    "matchType":1,
    "name":"Energy saving scene with human presence",
    "newLocalScene":false,
    "preConditions":[
        {
            "condType":"timeCheck",
            "expr":{
                "timeZoneId":"Asia/Shanghai",
                "start":"00:00",
                "loops":"1111111",
                "timeInterval":"allDay",
                "end":"23:59",
            },
            "holiday":{
              	    "support":true, //true: execute on public holidays, false: not execute on public holidays
              	    "regionCode":"CHN" // The area code
             },
             "stopDates":[//Disabled time period
              {
                  "start":"20230501",
                  "end":"20230505"
              },
              {
                  "start":"yyyyMMdd",
                  "end":"yyyyMMdd"
              }
            ],
        }
    ],
    "projectId":"1405014271166902272",
    "type":3
}

Sample response

For more information about the sample response, see Query the list of smart linkage.

Update a smart linkage

API description

Update a specified smart linkage.

API endpoint

Linkage: POST /v1.0/illumination/smart/linkage/update
Schedule: GET /v1.0/illumination/smart/schedule/update

Request parameters

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

Response parameters

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

Enable or disable a rule

API description

Enable or disable a specified rule.

API endpoint

POST /v1.0/illumination/smart/change-status

Request parameters

Parameter name	Type	Parameter type	Description	Required
ruleId	String	body	The ID of the specified rule.	No
enabled	boolean	body	Specifies whether to enable a rule.	No

Response parameters

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

Description of result

{}

Sample request

{
  "ruleId": "",
  "enabled": ""
}

Remove a linkage rule

API description

Remove a specified linkage rule.

API endpoint

POST /v1.0/illumination/smart/remove

Request parameters

Parameter name	Type	Parameter type	Description	Required
ruleId	String	body	The ID of the specified rule.	No

Response parameters

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

Sample request

{
  "ruleId": ""
}

Error codes

The following table lists common error codes returned in 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	The error message is returned because you are unauthorized to make the API request.

Prev DocSmart Scene

Next DocCustom Template of Scene Linkage