Overview
For this tutorial, we will create an Automation using the Rules API to change a device’s color-based on the time of the day. This example Rule will use the Color Control Capability, which allows us to manipulate a color-changing device (e.g. a light bulb) by setting its hue, saturation, and other color attributes. A complete sample of this Rule is available in the SmartThings Developers Github repository.
Prerequisites
- REST API client (such as Postman)
- Personal Access Token (PAT)
Crafting Your Rule
Rule Conditions
For this example, we will change the light color when the device is turned ON between sunrise (start
) and one hour after sunrise (end
).
We will build the Conditions using an If
action block starting with the logical operator and
to include operations between
and equals
.
The between
operation has three properties:
- Value: (type:
time
) checks thestart
andend
values to see if it is inside the range. In this case, the referenceNow
is used because we want to check if the current time is between thestart
andend
values. - Start: (type:
time
) This value defines the range beginning. For this example, it is set to “Sunrise”. - End: (type:
time
) This value defines the range finish. As the supported standard values areNow
,Midnight
,Sunrise
,Noon
andSunset
, we are adding anoffset
to refer to “one hour after sunrise”.
In the code snippet below, we are also looking at the light to see if it is already turned on. For this, we use an equals
operation, which compares the value of the device’s Switch capability.
- Right: Sets the device and Capability’s attribute to compare
- Left: Defines the target attribute value. In this context, we are seeking
string: on
.
"if":{
"and":[
{
"between":{
"value": {
"time": {
"reference": "Now"
}
},
"start": {
"time": {
"reference": "Sunrise"
}
},
"end": {
"time": {
"reference": "Sunrise",
"offset": {
"value": {"integer":1},
"unit": "Hour"
}
}
}
}
},
{
"equals": {
"left": {
"device": {
"devices": [
"{{ light-deviceId }}"
],
"component": "main",
"capability": "switch",
"attribute": "switch"
}
},
"right": {
"string": "on"
}
}
}
]
//Command
}
Rule Result
Once the conditions are met, the Rule will transition to execute the result (then
actions). To change the color of a device, we are going to use the Color Control Capability and the setColor
Command.
The setColor
command receives the argument color
which is type Object
. This means we must send a map as an argument.
Using the above steps, we are setting the value to a soft yellow color.
"then":[
{
"command": {
"devices": [
"{{ light-deviceId }}"
],
"commands": [
{
"component": "main",
"capability": "colorControl",
"command": "setColor",
"arguments": [
{
"map":{
"hue": {
"decimal": "10.833333333333334"
},
"saturation": {
"decimal": "40"
}
}
}
]
}
]
}
}
]
We’ve put a complete sample of this Color Changing Light Bulb Automation in our SmartThings Developers Samples Rules repository.
Uploading Your Rule
We are going to use the Rules API to upload this example to our Samsung account. You can use your preferred REST client, as long as you’re able to configure the Authorization
and Content
headers correctly (see below the step 5
). For this example, we are using Postman.
- Open the API client and create a new POST request.
- Enter the Rules request URL (https://api.smartthings.com/v1/rules).
- Add the target location ID as a query parameter. For example:
https://api.smartthings.com/rules?locationId=location-id
- Navigate to the Authorization tab; select Bearer Token as type and add your PAT.
- Select the Body tab, select
Raw
andJSON
. Then, paste your custom Rule.
Steps 4 and 5 generate the following headers:
Authorization: Bearer PAT
Content-Type: application/json
If your Rule is formatted correctly when you POST your request, you will receive a 200 (Ok)
code and the following properties will be shown in the request result:
"id": "d2099bc3-6a2f-xxxx-xxxx",
"status": "Enabled",
"executionLocation": "Local", //or Cloud
"ownerType": "Location",
"ownerId": "0b018721-6bc0-xxxx-xxxx",
"creator": "SMARTTHINGS",
"dateCreated": "timestamp",
"dateUpdated": "timestamp"
Additional Resources
Here are some additional resources to help you build custom Automations with the Rules API:
- Sample Rules on SmartThings Developers GitHub
- Rules API Helper
- How we used Rust to build Rules Engine on Samsung Developers Blog
Have questions or requests for more samples? Drop a note in the Community!