Method to have a rule trigger on location mode change?

Developer Programs Rules API
1

Can someone tell me how to have a rule trigger on a location’s mode change?

I presume i use the “changes” condition, but the parameters are not clear to me. I did find two example rules in ST’s repository that referenced location mode state, but i’m still unclear on details for my case (e.g. change from Home to Away). Is “location” a special device in context of rules, and do i use the uuid’s I find that are specific to my hub’s location in the parameters?

ref:

		"if": {
			"equals": {
				"left": {
					"location": {
						"attribute": "Mode"
					}
				},
				"right": {
					"string": "{{away_uuid}}"
				}
			},
3

I actually explicitly set the locationId in the parameters because I like to emphasise that the Mode IDs are Location specific. I think it works without it but I haven’t checked.

Just to make this post more useful for others …

In Rules you need to use your unique identifiers rather than labels. So you use the UUID of your Location, which is the locationId in the API object. Similarly for Modes you need the id from the API object.

Here is an example where the Location Mode being set to Away triggers a corresponding change in the Security Mode.

{
    "name": "[R] Security: Away",
    "actions": [
        {
            "if": {
                "equals": {
                    "left": {
                        "location": {
                            "locationId": "{{LocationId}}",
                            "attribute": "Mode"
                        }
                    },
                    "right": {
                        "string": "{{AwayModeId}}"
                    }
                },
                "then": [
                    {
                        "location": {
                            "locationId": "{{LocationId}}",
                            "security": {
                                "armState": "ArmedAway"
                            }
                        }
                    }
                ]
            }
        }
    ]

Just for completeness, here is a code snippet for setting the Mode.

                "then": [
                    {
                        "location": {
                            "locationId": "{{LocationId}}",
                            "mode": "{{StayModeId}}"
                        }
                    }
                ]
4

If you don’t mind me asking, why is the “equals” condition used as the trigger, instead of the “changes” condition? (I’m new to rules programming and probably ask about obvious known stuff.)

5

As I understand things, when you add Location or Device operands to a Rule, the Rule (which is a type of app) subscribes to the relevant Location or Device attributes. When an event comes in the Rule immediately updates the value of the affected conditions. So it always knows the current value of the attributes.

Unless you specify otherwise with the trigger property, the Rule is then immediately triggered / activated / executed / run or whatever you want to call it. Basically it evaluates the if and runs the then or else actions accordingly.

So in the example the equals condition is comparing the current Location Mode to a specified one (which happens to have the ‘Away’ label but the Rule doesn’t know that). If the Location Mode changes to ‘Away’ the Rule triggers. It would also trigger if an event is received and it is remain ‘Away’.

It’s basically the same as a condition in an app Routine. If you set the trigger property to never it is the same as a precondition.

The changes condition is a higher level condition that is described as only returning true if its child condition changes from false to true. So if you added it as a parent to equals in the example the Rule would only run the then action when the mode changes to Away, not if it was already Away. That sort of thing can be valuable. However a number of conditions also have their own properties that have largely the same effect without changes being needed.

I’ve actually only used changes in a changes > operand > device hierarchy to detect changes in non-binary devices such as temperature sensors for mirroring purposes. You’d never know you could do this from the documentation. It remains a mystery to me how the hopelessly described operand condition turns that into the false or true that changes is said to work on.