Best practices for scene automation
The IoT Platform scene automation feature is based on the Thing Specification Language (TSL) model. It uses logical rules to orchestrate device TSL models and actions for automated execution.
Overview
The platform provides a set of APIs for automation scenarios. These APIs use the OAuth 2.0 protocol for authentication. For more information, see Scene service.
This section describes several common patterns for creating scenarios.
Scenario pattern | Rule description | Notes |
TCA (Trigger, Condition, and Action) |
| An IFTTT (If This Then That) rule is a JSON description that includes four parts: `type`, `trigger`, `condition`, and `action`. You set a trigger that, when its conditions are met, automatically executes an action. |
CA (Condition and Action) |
The same device property cannot be set more than once. The condition and action cannot be set for the same device property. | Scenarios created in CA mode fall into two cases:
|
Condition details
A condition typically supports a time point, device property, and time period. The following sections provide sample code for each type.
Time point
Specifies a point in time when the corresponding task is allowed to run.
{ "uri": "condition/timer", "params": { "cron": "", // A cron expression. For more information, see http://crontab.org/. "cronType": "", // The expression type. Supported values are `linux` and `quartz_cron`. `linux` indicates a 5-field crontab expression. `quartz_cron` indicates a 7-field Quartz expression that supports the year. The minimum time unit is minutes. The first field, which represents seconds, must be `0`. "timezoneID": "" // The time zone. } }Time range
Specifies the time period on a specific day of the week during which the task can run.
{ "uri": "condition/timeRange", "params": { "format": "", // The time format is `HH:mm`. "beginDate": "", // The start time. For example, `08:30` means the condition becomes effective at 8:30 AM. "endDate": "", // The end time. For example, `23:00` means the condition is effective until 11:00 PM. "repeat": "", // The days to repeat. For example, `1,2,3` means the task can run on Monday, Tuesday, and Wednesday. Use numbers from 1 (Monday) to 7 (Sunday), separated by commas (,). "timezoneID": "" // The time zone. } }Device property
Triggers the corresponding task when a device property changes to a specific value.
{ "uri": "condition/device/property", "params": { "productKey": "", // The ProductKey of the product. "deviceName": "", // The DeviceName of the device. "propertyName": "", // The unique identifier of the property. It must be unique within a product. This is the `identifier` of a property in the TSL model. "compareType": "", // The comparison type. Supported values are `>`, `<`, and `==`. "compareValue": "" // The property value to compare. The data type of this value must match the `type` of the property in the TSL model. For example, if the `type` is `int` or `float`, `compareValue` is a number. If the `type` is `text`, `compareValue` is a string. } }
Action details
The following action types are supported.
Device property
Sets a device property if a condition is met.
{ "uri": "action/device/setProperty", "params": { "iotId": "", // The device ID. "propertyValue": "", // The property value to set. "propertyName": "" // The unique identifier of the property. It must be unique within a product. This is the `identifier` of a property in the TSL model. } }Device service
Invokes a device service when the condition is met. To create this action, you must set all properties for the device service.
{ "uri": "action/device/invokeService", "params": { "iotId": "", // The device ID. "serviceName": "", // The service name. This is the `identifier` of a service in the TSL model. "serviceArgs": {} // The set of service parameters. The key is the `identifier` of an item in the `inputData` of the service in the TSL model. The value is the value of that `inputData` item. } }Scenario
Triggers a scenario when the condition is met.
{ "uri": "action/scene/trigger", "params": { "sceneId": "" // The scenario ID. } }Send notification
Sends a notification to the current user when the condition is met.
{ "uri": "action/mq/send", "params": { "msgTag": "IlopBusiness_CustomMsg", // A fixed rule tag for the notification message. "customData": { "message": "" // The notification content. The content can be up to 60 characters in length. } } }
Create an automation scenario (Example 1)
This example shows how to create an automation scenario. It uses a device switch as the condition and sending a notification as the action. The development flow is as follows.
Retrieve the device properties.
Use the List the functional properties that support TCA configuration on a device API to retrieve the device properties. The following code shows sample request parameters.
"params" : { "iotId" : "dhS41YnxxxxYx000101", // The device ID. "flowType" : 1 // `1` indicates a condition. `2` indicates an action. The cloud filters out unsupported properties and services based on `flowType`. }Select the Main Light Switch property as the condition and set its value to 1. The following code shows the response. The propertyName is the identifier of the selected property. The notification content is set to `Demo: Create automation`.
"data" : { "abilityDsl" : { // `abilityDsl` is the TSL data of the device. "properties" : [ // `properties` is the list of properties in the device TSL. { "required" : true, "accessMode" : "rw", "identifier" : "LightSwitch", "dataType" : { "specs" : { // `specs` contains the optional values and their names. "0" : "Off", "1" : "On" }, "type" : "bool" // `type` is the data type of the property value. }, "name" : "Main Light Switch" } ], "services" : [ { "method" : "thing.service.property.set", "callType" : "async", "desc" : "Set property", "outputData" : [ ], "identifier" : "set", "required" : true, "inputData" : [ { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" } ], "name" : "set" }, { "method" : "thing.service.property.get", "callType" : "async", "desc" : "Get property", "outputData" : [ { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" } ], "identifier" : "get", "required" : true, "inputData" : [ "LightSwitch" ], "name" : "get" } ], "schema" : "https:\/\/iotx-tsl.oss-ap-southeast-1.aliyuncs.com\/schema.json", "profile" : { "productKey" : "a1xxxxG" }, "events" : [ { "method" : "thing.event.property.post", "outputData" : [ { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" } ], "identifier" : "post", "type" : "info", "required" : true, "name" : "post", "desc" : "Report property" }, { "type" : "error", "required" : true, "method" : "thing.event.Error.post", "identifier" : "Error", "name" : "Report fault", "outputData" : [ { "dataType" : { "specs" : { "0" : "Normal" }, "type" : "enum" }, "name" : "Fault Code", "identifier" : "ErrorCode" } ] } ] }, "simplifyAbilityDTOs" : [ { "type" : 1, // The value in the `simplifyAbilityDTOs` property list. `1` indicates a property, `2` indicates a service, and `3` indicates an event. "identifier" : "LightSwitch", // `propertyName` is the identifier of the device property. Here, the value is `LightSwitch`. "categoryType" : "Light", "name" : "Main Light Switch" } ] }Create the automation scenario.
Use the Create a scenario API to create the automation scenario. The following code shows an example.
"params" : { "enable" : true, "icon" : "http://gaic.alicdn.com/ztms/cloud-intelligence-icons/icons/scene_img_xxxx_1.png", "mode" : "all", "catalogId" : "1", "caConditions" : [ { "uri" : "condition/device/property", "params" : { "propertyName" : "LightSwitch", "productKey" : "a1xxxx7G", "compareValue" : 1, "compareType" : "==", "deviceName" : "VDxxxxx15RH" } } ], "sceneType" : "CA", "actions" : [ { "uri" : "action/mq/send", "params" : { "customData" : { "message" : "Demo: Create automation" // Set the notification content. }, "msgTag" : "IlopBusiness_CustomMsg" } } ], "name" : "Demo: Create automation", "iconColor" : "#A86AFB" }
Scene automation (Example 2)
This example shows how to create an automation scenario. It uses a time point (repeats at 13:35 from Monday to Friday in the Chinese mainland) as the condition and a device service as the action. The development flow is as follows.
Set the time point.
{ "uri" : "condition/timer", "params" : { "timezoneID" : "Asia/Shanghai", "cron" : "35 13 * * 1,2,3,4,5", "cronType" : "linux" } }Retrieve the device properties.
Use the List the functional properties that support TCA configuration on a device API to retrieve the device properties. The following code shows sample request parameters.
"params" : { "iotId" : "z2v7EHHxxxxoWs000100", "flowType" : 2 // `2` indicates an action. The cloud filters out unsupported properties and services based on `flowType`. }The following result is returned.
"data" : { "abilityDsl" : { // `abilityDsl` is the TSL data of the device. "properties" : [ // `properties` is the list of properties in the device TSL. { "required" : true, "accessMode" : "rw", "identifier" : "LightSwitch", "dataType" : { "specs" : { // `specs` contains the optional values and their names. "0" : "Off", "1" : "On" }, "type" : "bool" // `type` is the data type of the property value. }, "name" : "Main Light Switch" }, { "required" : true, "accessMode" : "rw", "identifier" : "WIFI_Band", "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Frequency Band" }, { "required" : true, "accessMode" : "rw", "identifier" : "WiFI_RSSI", "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "-1", "step" : "1" }, "type" : "int" }, "name" : "Signal Strength" }, { "required" : true, "accessMode" : "rw", "identifier" : "WIFI_AP_BSSID", "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Hotspot BSSID" }, { "required" : true, "accessMode" : "rw", "identifier" : "WIFI_Channel", "dataType" : { "specs" : { "unitName" : "None", "min" : "1", "max" : "255", "step" : "1" }, "type" : "int" }, "name" : "Channel" }, { "required" : true, "accessMode" : "rw", "identifier" : "WiFI_SNR", "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "127", "step" : "1" }, "type" : "int" }, "name" : "Signal-to-Noise Ratio" } ], "services" : [ { "method" : "thing.service.property.set", "callType" : "async", "desc" : "Set property", "outputData" : [ ], "identifier" : "set", "required" : true, "inputData" : [ { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" }, { "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Frequency Band", "identifier" : "WIFI_Band" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "-1", "step" : "1" }, "type" : "int" }, "name" : "Signal Strength", "identifier" : "WiFI_RSSI" }, { "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Hotspot BSSID", "identifier" : "WIFI_AP_BSSID" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "1", "max" : "255", "step" : "1" }, "type" : "int" }, "name" : "Channel", "identifier" : "WIFI_Channel" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "127", "step" : "1" }, "type" : "int" }, "name" : "Signal-to-Noise Ratio", "identifier" : "WiFI_SNR" } ], "name" : "set" }, { "method" : "thing.service.property.get", "callType" : "async", "desc" : "Get property", "outputData" : [ { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" }, { "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Frequency Band", "identifier" : "WIFI_Band" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "-1", "step" : "1" }, "type" : "int" }, "name" : "Signal Strength", "identifier" : "WiFI_RSSI" }, { "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Hotspot BSSID", "identifier" : "WIFI_AP_BSSID" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "1", "max" : "255", "step" : "1" }, "type" : "int" }, "name" : "Channel", "identifier" : "WIFI_Channel" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "127", "step" : "1" }, "type" : "int" }, "name" : "Signal-to-Noise Ratio", "identifier" : "WiFI_SNR" } ], "identifier" : "get", "required" : true, "inputData" : [ "LightSwitch", "WIFI_Band", "WiFI_RSSI", "WIFI_AP_BSSID", "WIFI_Channel", "WiFI_SNR" ], "name" : "get" }, { "method" : "thing.service.ToggleLightSwitch", "callType" : "async", "outputData" : [ ], "identifier" : "ToggleLightSwitch", "required" : false, "inputData" : [ { "dataType" : { "specs" : { "min" : "1", "max" : "100", "unit" : "count", "step" : "1" }, "type" : "int" }, "name" : "Test 1", "identifier" : "test1" }, { "dataType" : { "specs" : { "min" : "1", "max" : "10", "unit" : "mm\/s", "step" : "0.1" }, "type" : "float" }, "name" : "Test 2", "identifier" : "test2" } ], "name" : "Flip Main Light Switch" }, { "method" : "thing.service.SetLightSwitchTimer", "callType" : "async", "outputData" : [ ], "identifier" : "SetLightSwitchTimer", "required" : false, "inputData" : [ { "dataType" : { "specs" : { "unitName" : "min", "min" : "0", "max" : "1440", "unit" : "min", "step" : "0.01" }, "type" : "double" }, "name" : "Timer", "identifier" : "Timer" }, { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" } ], "name" : "Set Main Light Switch Countdown" }, { "method" : "thing.service.ControlDevice", "callType" : "sync", "outputData" : [ { "dataType" : { "specs" : { "min" : "0", "max" : "99999", "unitName" : "None" }, "type" : "int" }, "name" : "Return Code", "identifier" : "Code" }, { "dataType" : { "specs" : { "length" : "128" }, "type" : "text" }, "name" : "Return Message", "identifier" : "Message" } ], "identifier" : "ControlDevice", "required" : false, "inputData" : [ { "dataType" : { "specs" : { "length" : "64" }, "type" : "text" }, "name" : "Host ID", "identifier" : "HostId" }, { "dataType" : { "specs" : { "length" : "64" }, "type" : "text" }, "name" : "Geofence ID", "identifier" : "EfenceId" }, { "dataType" : { "specs" : { "length" : "64" }, "type" : "text" }, "name" : "Action", "identifier" : "Action" } ], "name" : "Control Device" } ], "schema" : "https:\/\/iotx-tsl.oss-ap-southeast-1.aliyuncs.com\/schema.json", "profile" : { "productKey" : "a1xxxxxska" }, "events" : [ { "method" : "thing.event.property.post", "outputData" : [ { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" }, { "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Frequency Band", "identifier" : "WIFI_Band" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "-1", "step" : "1" }, "type" : "int" }, "name" : "Signal Strength", "identifier" : "WiFI_RSSI" }, { "dataType" : { "specs" : { "length" : "255" }, "type" : "text" }, "name" : "Hotspot BSSID", "identifier" : "WIFI_AP_BSSID" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "1", "max" : "255", "step" : "1" }, "type" : "int" }, "name" : "Channel", "identifier" : "WIFI_Channel" }, { "dataType" : { "specs" : { "unitName" : "None", "min" : "-127", "max" : "127", "step" : "1" }, "type" : "int" }, "name" : "Signal-to-Noise Ratio", "identifier" : "WiFI_SNR" } ], "identifier" : "post", "type" : "info", "required" : true, "name" : "post", "desc" : "Report property" }, { "type" : "error", "required" : true, "method" : "thing.event.Error.post", "identifier" : "Error", "name" : "Report fault", "outputData" : [ { "dataType" : { "specs" : { "0" : "Recovered" }, "type" : "enum" }, "name" : "Fault Code", "identifier" : "ErrorCode" } ] } ] }, "simplifyAbilityDTOs" : [ { "type" : 1, "identifier" : "LightSwitch", "categoryType" : "Light", "name" : "Main Light Switch" }, { "type" : 1, "identifier" : "WiFI_RSSI", "categoryType" : "Light", "name" : "Signal Strength" }, { "type" : 1, "identifier" : "WIFI_Channel", "categoryType" : "Light", "name" : "Channel" }, { "type" : 1, "identifier" : "WiFI_SNR", "categoryType" : "Light", "name" : "Signal-to-Noise Ratio" }, { "type" : 2, "identifier" : "ToggleLightSwitch", "categoryType" : "Light", "name" : "Flip Main Light Switch" }, { "type" : 2, "identifier" : "SetLightSwitchTimer", "categoryType" : "Light", "name" : "Set Main Light Switch Countdown" }, { "type" : 2, // The value in the `simplifyAbilityDTOs` property list. `1` indicates a property, `2` indicates a service, and `3` indicates an event. "identifier" : "ControlDevice", // `propertyName` is the identifier of the device property. Here, the value is `ControlDevice`. "categoryType" : "Light", "name" : "Control Device" } ] }`abilityDsl` is the TSL data of the device. `services` is the list of services in the device TSL. `inputData` in `services` is the list of properties that must be set for the service. You also need to configure the following TSL information.
// The following code shows a service in the TSL. { "method" : "thing.service.SetLightSwitchTimer", "callType" : "async", "outputData" : [ ], "identifier" : "SetLightSwitchTimer", "required" : false, "inputData" : [ // `inputData` is the list of properties that must be set for the service. { "dataType" : { "specs" : { "unitName" : "min", "min" : "0", "max" : "1440", "unit" : "min", "step" : "0.01" }, "type" : "double" }, "name" : "Timer", "identifier" : "Timer" }, { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" } ], "name" : "Set Main Light Switch Countdown" }The following result is returned.
{ "method" : "thing.service.SetLightSwitchTimer", "callType" : "async", "outputData" : [ ], "identifier" : "SetLightSwitchTimer", "required" : false, "inputData" : [ { "dataType" : { "specs" : { "unitName" : "min", "min" : "0", "max" : "1440", "unit" : "min", "step" : "0.01" }, "type" : "double" }, "name" : "Timer", "identifier" : "Timer" }, { "dataType" : { "specs" : { "0" : "Off", "1" : "On" }, "type" : "bool" }, "name" : "Main Light Switch", "identifier" : "LightSwitch" } ], "name" : "Set Main Light Switch Countdown" // The service named "Set Main Light Switch Countdown" is used as the action. }To use a service as the action, you must set values for all properties that the service contains, such as `Timer` and `Main Light Switch`. Set `Timer` to 0.08 and `Main Light Switch` to 1. The following code shows an example.
{ "uri" : "action/device/invokeService", "params" : { "iotId" : "z2v7EHHfExxxxWs000100", "serviceName" : "SetLightSwitchTimer", // SetLightSwitchTimer, which is a service in the TSL. "serviceArgs" : { // {property identifier: property value} "Timer" : 0.08, // Set the timer value to 0.08. "LightSwitch" : 1 // Set the main light switch value to 1. } } }Create the automation scenario.
Use the Create a scenario API to create the automation scenario. The following code shows an example.
"params" : { "enable" : true, "icon" : "http://gaic.alicdn.com/ztms/cloud-intelligence-icons/icons/scene_xxxx_15.png", "mode" : "all", "catalogId" : "1", "caConditions" : [ { "uri" : "condition/timer", "params" : { "timezoneID" : "Asia/Shanghai", "cron" : "35 13 * * 1,2,3,4,5", "cronType" : "linux" } } ], "sceneType" : "CA", "actions" : [ { "uri" : "action/device/invokeService", "params" : { "iotId" : "z2v7EHHfxxxxoWs000100", "serviceName" : "SetLxxxxxTimer", // SetLightSwitchTimer, which is a service in the TSL. "serviceArgs" : { "Timer" : 0.08, "LightSwitch" : 1 } } } ], "name" : "Xiaoqing-Lamp-My-Little-Bulb-Set-Main-Light-Switch-Countdown", "iconColor" : "#FF454F" }
Create a manually triggered scenario
An automation scenario is a task that automatically triggers actions based on conditions. A manually triggered scenario, however, runs only when a user manually executes it. Therefore, a manually triggered scenario contains only a series of actions and no conditions.
Create a manually triggered scenario
This example shows how to create a manually triggered scenario that turns on a fan.
Use the Create a scenario API to create the scenario. The following code shows an example.
"params":{ "enable":true, "icon":"http://gaic.alicdn.com/ztms/cloud-intelligence-icons/icons/scene_img_xxxx_13.png", "iconColor":"#738DE1", "name":"Jiajia-Fan-01-Power-Switch-On", "actions":[ { "uri":"action/device/setProperty", "params":{ "propertyName":"PowerSwitch", "iotId":"bx6lzXLxxxxLNOO000101", "propertyValue":1 } } ], "catalogId":"0" }NoteCreating a manually triggered scenario is similar to creating an automation scenario. The difference is that a manually triggered scenario does not have `caConditions`. You also do not need to pass the optional `sceneType` and `mode` parameters.
Execute a manually triggered scenario
Use the Execute a scenario API to execute the scenario. The following code shows an example.
params:{"sceneId":"7823be10xxxx8790f36bdc629e"}