Tutorial | Using Rules API to Control a Color-Changing Device

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

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:

  1. Value: (type: time) checks the start and end values to see if it is inside the range. In this case, the reference Now is used because we want to check if the current time is between the start and end values.
  2. Start: (type: time) This value defines the range beginning. For this example, it is set to “Sunrise”.
  3. End: (type: time) This value defines the range finish. As the supported standard values are Now, Midnight, Sunrise, Noon and Sunset, we are adding an offset 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.

  1. Open the API client and create a new POST request.
  2. Enter the Rules request URL (https://api.smartthings.com/v1/rules).
  3. Add the target location ID as a query parameter. For example:
https://api.smartthings.com/rules?locationId=location-id
  1. Navigate to the Authorization tab; select Bearer Token as type and add your PAT.
  2. Select the Body tab, select Raw and JSON. 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:

Have questions or requests for more samples? Drop a note in the Community!

6 Likes

Thanks for this example @nayelyz

Does “random” exists within Rules api? Say for instance you wanted to choose a random color amongst a defined set of colors.

As an example (taken from Home assistant forum)

message: {{ [“OK”, “Sure”, “If you insist”, “Done”] | random }}

1 Like

Or we could just use webCoRE to achieve the same thing in under 1 minute:

But shoot, you are killing that aren’t you, what a Smart Thing to do!!!

3 Likes

How would you start a tutorial to learn something new, with the most complicated or the simplest? Your comparison is too simple.

When you already know how to read and write in one language, the least you want is to have to learn another new language.

That does not mean that the language you know is more useful and better globally than the new one.

Example, very few thought that the new Edge driver would improve so much what seemed irreplaceable, groovy.

Well this seems the same to me, I would like not to have to learn webcore or API of .json rules

I would like it to be much easier.
Your rule With webcore in 1 minute.
The same rule made in the mobile app in 30 seconds and 99% of users can do:

But not all the rules that we need can be as simple as these and other tools are needed.

Or is it that making a complex rule in webcore is easy for 90% of users?

3 Likes

This is not supported yet, but the engineering team keeps improving the development tools. I’ll share your comments with them.

Thanks for sharing!

1 Like

This sample is to show the Community how to use a complex capability such as colorControl in the Rules API.
There are other samples in the SmartThings Developers Github repository using different conditions which you can combine to create your own Rules, I love to see the things you achieve using the development tools.
Also, if you have a Rule case in mind you can share it in the Developers section and we can discuss it.

This topic was automatically closed 3 days after the last reply. New replies are no longer allowed.