Hi, I have been trying to develop an smartapp myself using postman and some scripts for registering smartapps and then creating virtual devices.Now I have done all of them. My question here is related to rules and how they are triggered. I know that we set rules for a room or a location and then we put a virtual device there and rules are now related to devices. I checked it on the Smartthings app and saw that when I, for example, change some parameter and then execute a rule in my postman using ExecuteRule request in SmartthingsAPI then I can see the change of status of my device in the Smartthings Application and also by postman request.
My actual question here is that I always thought that rules are here to be triggered not by just being executed by sending a random request from postman. So I don’t know what’s happening. Are rules just executed by this command or they are some eventsor maybe sth which can trigger the rule?
Also we have a CreateDeviceEvents request in the Smartthings API which is not said how is the structure of the request.(I mean it says that it’s a post request but hasn’t spoken about the body of it and it’s empty).
So I would be glad if you could tell me how is the structure of devices, rules and triggers are working here
It sounds like you’ve probably been toying with the ‘Rules API’, the common name for the /rules endpoint on the public API.
The Automatic and Manually Run Routines (Scenes) that you create in the SmartThings App are also implemented as Rules. As are the preset Routines you find on some of the device pages, the templated Routines on the ‘Discover’ page, and the automations created by Smart Lighting.
So the conditions of a Routine are the if block in a Rule, and the actions are the then block. A ‘Room Light is on’ condition in a Routine is the equals operation comparing the the switch attribute of the switch capability of the main component of the device ‘Room Light’ to the string on. And so on.
So how does a Rule work? Well the Rule is basically the configuration settings for an instance of an app. Just like a SmartApp the Rule app can subscribe to device events and that is what it does. It subscribes to all the device events that could affect a condition in the Rule. So in the above example it subscribes to the switch attribute of the switch capability of the main component of the device ‘Room Light’. When the ‘Room Light’ turns on or off it sends out an event and that is received by the Rule app which then updates its status accordingly.
We were talking about a condition of a Routine. Routines might need to do something when a condition changes. So the Rule is then ‘executed’ to see whether it needs to do something. Or if you prefer, it has been triggered.
Had it been a pre-condition of a Routine the Rule would not have been executed. The conditions would just have been updated ready for the next trigger event to happen.
As you have discovered, you can execute a Rule directly via the API if you so wish. That is what you are doing when you run a Manually Run Routine (Scene) in the mobile apps.
OK. In SmartThings device events are the way the attributes of a device are updated. In the legacy device handlers we would either ‘create’ or explicitly ‘send’ an event. In Edge drivers we ‘emit’ an event. It is all basically the same concept.
It is possible to use a SmartApp to implement a cloud device. The SmartApp can instruct the API to create and install a device based on a given device profile. The SmartApp will need to manage the status of this device so it needs its own way to generate the necessary device events. That is what Create Device Events is for. The same thing happens with VIRTUAL devices (the ones made via the API).
Thanks for your response. I think you misunderstood my question. I was asking if there is a way to create device events using the API Documentation because the body of the POST request in the Documentaion of CreateDeviceEvents is empty. My actual question moreover of that is that after creating rules and devices and apps also, how are they connected. I know that rules will be related to devices in same location with the rule but I wanted to know that if the status of a device changes then we have events to trigger the rule or we should manually run the execute rule?
I wanted to know this connection because I want to know that how devices will be related to rules because I couldn’t find the routines to be created there.If yes, then I should create them by creating presentation for devices and then adding it from Smartthings App?
You are absolutely correct, I didn’t understand the question. For that reason I replied with an overview about how Rules work and are tied in with devices and events, basing my description on the more familiar Routines (which are implemented as Rules), hoping I would cover what you needed to know.
Ah right, I hadn’t realised there was still an issue with missing payloads in the API Reference. That’s been a problem for a very long time. However all the information you need to create the request is there…
As I explained, the ‘Create Device Events’ API request has a very specific purpose. An example of the body of the post would be in the form:
{
"deviceEvents": [
{
"component": "main",
"capability": "switch",
"attribute": "switch",
"value": "on"
}
]
}
I did cover that. The Rule receives the same device events that set the attribute status and automatically executes if required.
I am not sure exactly what the question is here so I will take a guess. I think that perhaps you are concerned that when you create Rules via Postman (or in other ways) you don’t see any evidence of them in the SmartThings app.
If that is the question, then the reason is simply that the SmartThings app is a relatively simple tool aimed at end-users. The app maintains its own set of simple automations called Routines which are based on Rules, but they are kept separate because they don’t want them messed around with outside of the app. The ‘Rules API’ is considered to be an advanced/developer tool that the SmartThings app has no need to concern itself with.
I still don’t feel like I’ve answered the question.
Oh, thanks I got that. I think I just have one more question about your answer.
Before your response I thought that after creating rules, each time I change the attribute of a device I have to run the ExecuteRule command to check the rules. Now you mean that by creating device events just 1 time for all sake, then after each time the status changes it automatically checks the status of the rules itself and no need for me to send the request of executeRule?
Think about creating a Routine in the mobile app. You hit the ‘+’ button and the ‘Create routine’ page opens up. You are assisted in building a Routine and eventually you hit the ‘Save’ button and give the Routine a name. You hit ‘Save’ again and the rule is created. Job done, it just starts working with no more intervention from you.
What has basically happened is that you have created a JSON input file for the API, and when you hit ‘Save’ for the second time you have POSTed that JSON to the /rules endpoint of the API. You have literally created a Rule. They just call it a Routine.
So basically you just have to create the JSON for a Rule and post it to the API and everything else will be taken care of for you.
From my last talk with one of the others from SmartThings team, he told me that creating a Routine in the mobile add needs a presentation for the device which I should create it using the API.
I created the rule for myself and that’s why I know how to work with Execute Rule.
Do you know another way instead of creating presentation? Because the Create Routine option in my mobile app is off for now.
OK, I am beginning to understand more of the questions now.
The mobile app needs to know how it should create the user interface for your device in a number of places. It needs to know how it should display the device tile on the room view and how to display the controls in the details view. The most important thing in this case is that it needs to know how to offer you the choice of device attributes for Routine conditions, and device commands for Routine actions.
Each Capability in SmartThings has an optional Capability Presentation that describes how that particular Capability should be presented in the UI in each of the places mentioned if it is selected for display in those places. Unless there is Capability Presentation that defines how that Capability appears in Routine conditions then it can’t appear in Routine conditions. A similar thing happens for Routine actions. There are a number of stock Capabilities that inexplicably do not have complete presentations and so can’t be used in Routines.
In addition to that there is a Device Presentation that specifies which Capabilities should be displayed in each place for the device. So if the Device Presentation doesn’t say a particular Capability should be included in Routine conditions then it won’t be. Similarly for Routine actions. Default Presentations do get created for Devices that display all Capabilities everywhere so you don’t always need to explicitly create them.
The result of all this is that unless you are using your own custom Capabilities with your own custom Capability Presentations, and using them in your own custom Device integration with your own Presentation, you can’t guarantee that you can use your device in a Routine in the way that you want because you are not in control of the situation. When this happens the Rules API can be the solution.
When you are creating Rules directly in the Rules API the Presentation is of no concern. You are the one doing the work unaided.
Hi, @Kiarash_Kianian
I think you’re referring to this conversation, right? Routine creating in smartthings mobile app - #9 by AlejandroPadilla
I don’t have more information to add to what @orangebucket mentioned because it’s complete. But, referring to that case, I remember the device profile didn’t have a presentation attached to it, so, that’s why you don’t see the option to create a routine.
If you create a device profile from the CLI, there’s a helper that allows you to select which capabilities to include and when you save it, it generates the presentation for you but only if you use the helper, if you use an input file, you will need to create that presentation and then add it to your profile’s metadata, so, I suggest you use it instead, you just need to run the command smartthings deviceprofiles and it’ll prompt you for the name and capabilities (one by one and using their ID - you can also list them and use their index number)
Or if you create them from the developer workspace, there’s an option to generate them automatically as well.
But, as Alejandro mentioned, if you don’t need to create something custom, you can use one of the standard virtual devices.
Thanks, this was so helpful.
I also wanted to know the relationship between the Rules, and the Execution of them. I wanted to know what makes them to be executed. In the actual system, is there sth that triggers them to be executed just when sth changes or they just execute in some period like every 10 seconds or sth?
It is all about events. Let’s just think about a simple condition like ‘Device A switch is on’. That is only ever going to change between false and true when the switch attribute changes value and when that happens the Rule receives an event telling it.
Similarly when you consider a Rule as a whole, the overall value of a combination of conditions can only have changed if one of the conditions has changed, so the Rule must have received an event.
So at its simplest, the Rule receives an event, it updates the conditions based on that event, and then executes the Rule in case the changes means it needs to do anything.
Sometimes you don’t want it to do that. Sometimes when an event is received you just want the Rule to know the conditions have changed but not actually act on those changes. So some conditions have settings to disable the execution (also called triggering) completely or under certain circumstances. That’s how the ‘preconditions’ in a Routine are implemented, and why ‘equal to or above’ conditions in Routines only execute the Routine on the false to true transition.
Conditions in Rules that allow you to control whether they result in a trigger usually default to ‘auto’. Apparently there is some internal logic that determines what ‘auto’ means in different situations. Unfortunately there is no information on what that logic actually is.
Let’s go back to keeping it simple though. The same events that are created in device handlers/drivers and are used to update the device attributes in SmartThings, will ultimately result in causing Rules to execute.