Announcing 'On Transition Only' Triggers

[josh]

We’re excited to announce not one, but two much-anticipated features! Today’s update includes a new On Transition Only option as well as generic ‘updates’ and ‘changes’ triggers.

On Transition Only

We’re debuting a new ‘On Transition Only’ option which refines your comparison to only take place when the value changes to your desired state. This nifty feature switches the operator from ‘updates and is XXX’ to ‘changes to XXX’.

This is helpful for situations where you only want the rule to trigger when a value ‘rises above’, ‘drops below’ or ‘changes from’ a specific value. This means that your rule will only be activated when the configured trigger initially transitions to true… and will only reactivate once the trigger leaves the configured state and re-enters it.

Any Update / Change

We’ve also introduced a new set of triggers that occur on any update or change to your specified attribute.

The first item in your list of operators is a new updates operator. This is much like the ‘updates and is’ operator, but you don’t need to specify a value to compare to. Instead, the rule will be triggered any time a new value is received for the attribute.

You can further refine this to only trigger on value changes by using the new changes operator. This functions much like the ‘updates’ operator, but requires that a value actually changes. Where the ‘updates’ operator triggers even if the device reported the same value again (eg. level=0 → level=0), the ‘changes’ operator only triggers when the value is different than its previously reported value.

[Nezmo]

This is great. Thanks @josh.

[Nezmo]

Updated about a dozen rules to use this today. Working like a dream.

[Smarthome_Chelmsford]

Fantastic additions! the update option alone has simplified so many rules and makes creating rules so much faster! THANK YOU!!!

[Carlos_Juarez]

Hi People, excuse me, maybe its for my lack of English, but I am still not getting the difference between update and change triggers. Can anybody give an practical example ? Thanks in advance.

[Sgt.Flippy_PJ]

@Carlos_Juarez Some values get updated, but don’t change. For example, a temperature device can update its temperature every 5 minutes, but the value stays the same. It will trigger every 5 minutes.

Change will only trigger if the actual value has changed. Instead of every 5 minutes when the device updates its temperature, it will only trigger if the temperature changes to a new value.

[josh]

Updates vs Changes

@Sgt.Flippy_PJ

For example, a temperature device can update its temperature every 5 minutes, but the value stays the same. It will trigger every 5 minutes.

Great example. Here’s my attempt at visualizing this.

With a generic updates (no comparison specified), when any value comes in, the ‘updates’ trigger would be fired.

But with a generic changes (no comparison specified), the new value would have to be different than the previous value for the trigger to fire.

On Transition Only

The same type of logic applies when the ‘On Transition Only’ option is selected for a trigger that has a comparison configured.

Regular (On Transition Only: ☐, unchecked)
The trigger would fire any time a value came in that matched the configured comparison.

On Transition Only: ✓ (checked)
The trigger would only fire the first time the trigger evaluated to true. If new events came in and the trigger continued to evaluate to true, the trigger would not fire again. A value would have to be received where the trigger is not true for it to ‘exit’, then a new value would have to come in that evaluates true again before an ‘On Transition Only’ would fire again.

Explanation

TLDR: The ‘On Transition Only’ will only trigger when the event value first transitions to the configured state. It won’t trigger again until the event value transitions out of the configured state.

Step-by-Step Timeline Description (tap to expand)

At t0, the value was 74 which is below the configured threshold so the rule is not triggered.

Then at t1, the reported value was 75 which is >74, so the rule would have been triggered under either the ‘On Transition Only’ or the regular trigger.

At t2, we see the benefit of the ‘On Transition Only’ setting.

• With the regular trigger, the new event would have evaluated and the rule would have seen it as >74 and triggered the rule to run again.
• But with ‘On Transition Only’, the rule would have known that it had already been triggered on a previous change to >74 and it had remained above 74, so it does not need to trigger again.

At t3, the new event value is below 74 and the trigger condition is not met, so neither configuration is triggered.

• Behind the scenes, the On Transition Only is internally reset at this point. It flags itself as the trigger not being matched, so the next time an event comes in that is matched, the system will know it’s a change in the trigger state.

At t4, the new value is >74, so the rule is triggered in either configuration.

• Regular Trigger: triggered any time the received event value matches the configuration
• On Transition Only: per the t3 notes, the system knows that the last event did not match the trigger configuration, and it knows that this new value is >74, so the rule is triggered.

At t5, the same logic as t2 applies. The regular trigger, is always triggered when it’s configured condition is met. And the On Transition Only, knows that it was already triggered and since the received events stayed triggered, it doesn’t need to trigger again.

Naming
The same type of language is used with these triggers as well (‘updates’ vs ‘changes’). The regular trigger would read:

…temperature updates and is greater than 74

And if you ticked the box for ‘On Transition Only’, the trigger would read:

…temperature changes to greater than 74

[Carlos_Juarez]

Got it my friend, Thanks !

[Carlos_Juarez]

I had seen the light ! Thanks Josh !

[Allan_P]

@josh, so in the case of a rule that is triggered by a variable changing to True, then the two methods are equivalent, right?

That is,

Updates and is True
is the same as
Changes to True

Also, if I create a rule that is triggered by a variable changing to True, then immediately set it to False, do some stuff, then wait for a 5 minute delay, then at the end set the variable to True (yes, I am creating a loop), does the trigger set off a new instance of the executing rule while the earlier one is completing, and is that a problem?

[josh]

@Allan_P

so in the case of a rule that is triggered by a variable changing to True, then the two methods are equivalent, right?

That is,

Updates and is True
is the same as
Changes to True

No, they are not equivalent.

With the updates variant, the rule will be triggered any time the variable value updates. So even if it was already true and the value was set to true again, the rule would trigger again with updates as the value would be considered updating (eg. true → true → true = newly written, new timestamp).

That’s where changes (On Transition Only) is useful as you can indicate that you only want the rule to be triggered when the value changes rather than any time it is updated. With changes, the value would have to change to a different value before it would trigger again (eg. true → false → true)

@Allan_P

does the trigger set off a new instance of the executing rule while the earlier one is completing, and is that a problem?

Yes, the rule will execute each time the trigger condition occurs. As for if it’s a problem, that depends on your needs and rule design. You might consider posting in one of the other community threads about that approach if you are interested as I’m sure other community members would have suggestions.

While I can’t provide guidance around this kind of looping as it’s not a stable approach to looping and not something we officially recommend, there are some general best-practices you can use to help with this sort of thing to try to minimize issues:

Unofficial Variable Loop Rule Best Practices

That being said, we are considering introducing a first class loop feature and are looking for feedback from the community on what use-cases they are using loops for (in general, event driven rules are preferred, but there are some use-cases where a loop makes sense)

[Allan_P]

@josh

the rule would trigger again with updates as the value would be considered updating (eg. true → true → true = newly written, new timestamp)

I get it now. Yeah, I wouldn’t have thought that would be an update, but I can see it happening especially if the source is coming from a linked service to ST.

I’m going to write a new rule to test to see if I even need the loop.

[Allan_P]

@josh , I’m not sure what I was thinking before with looping, but I just replaced it with an “On Transition” rule that works just as well, if not slightly better depending on the timing of the transition event. Thanks!

[Stephen_Boyle]

Hi - thanks for this feature! I am a little confused however once trying to implement this for the first time. It seems it is being triggered too many times and looking at the raw data i dont see the transition? maybe i am misinterpreting the logs.

for example, i have a rule that is triggered when the “Downstairs Temperature” CHANGES TO be greater or less than $StoveFanThreshold (which is 70).

An example log which triggered but shows that the temp when from 68.9 to 68.7 yet triggered this?

[
  {
    "type": "event",
    "subtype": "device",
    "data": {
      "platform": "hass",
      "locationId": "c895f307-3228-40eb-a131-0304dea57344",
      "objectId": "sensor.downstairs_temperature",
      "source": "DEVICE",
      "description": "",
      "descriptionText": "",
      "eventID": "01HMP29RGZ7CDCSM5Q4BYZJ10A",
      "value": 68.7,
      "isStateChange": true,
      "datetime": "2024-01-21T13:10:31.199Z",
      "attribute": "temperature"
    }
  },
  {
    "type": "state",
    "subtype": "variable",
    "data": {
      "platform": "sharptools",
      "uid": "LOrNZHBRr4WqlTP1LeSnyTavwDW2",
      "variableId": "StoveFanThreshold",
      "state": {
        "type": "Number",
        "value": 70,
        "timestamp": "2024-01-19T20:55:43.891Z",
        "isStateChange": true,
        "stateChangeTimestamp": "2024-01-19T20:55:43.891Z"
      }
    }
  },
  {
    "type": "state",
    "subtype": "variable",
    "data": {
      "platform": "sharptools",
      "uid": "LOrNZHBRr4WqlTP1LeSnyTavwDW2",
      "variableId": "StoveFanThreshold",
      "state": {
        "type": "Number",
        "value": 70,
        "timestamp": "2024-01-19T20:55:43.891Z",
        "isStateChange": true,
        "stateChangeTimestamp": "2024-01-19T20:55:43.891Z"
      }
    }
  },
  {
    "type": "cache",
    "subtype": "device",
    "data": {
      "platform": "hass",
      "locationId": "c895f307-3228-40eb-a131-0304dea57344",
      "objectId": "sensor.downstairs_temperature",
      "source": "DEVICE",
      "eventID": "01HMP248QRBKY6YAQM87KGF5JH",
      "value": 68.9,
      "datetime": "2024-01-21T13:07:31.192Z",
      "attribute": "temperature",
      "readtime": "2024-01-21T13:10:31.278Z"
    }
  }
]

i am also assuming that the first entry (by timestamp) shows the latest data and the last item is the previous entry it is comparing against for the transition.

this isnt a huge deal as i have further checks in my rule - but i am not sure why this transition is being triggered?

Also - when it gets closer to 70 and maybe flaps above and below (or close) - if my device is reporting in the tenths of the temp but i am comparing to an integer value of 70, does that do rounding on the device temp? should i maybe specify the threshold to be 70.0 ?

thanks so much!

[josh]

@Stephen_Boyle

CHANGES TO be greater or less than $StoveFanThreshold (which is 70).

That sounds like a bug. The ‘Transition Only’ option isn’t supposed to show up when a variable is used as the right-hand side of the comparison as we originally had some hesitation with the concept of ‘transition’ when a dynamic value could be used on the right side of the comparison.

That being said, I think it would be relatively straightforward to update the logic to support this, so I’ve made a note to take a closer look when we’re back in the office this week released an update to support it.

The implication of this is that when the right side of the comparison is a variable and that is dynamically updated, then the concept of a ‘change’ will always be relative to the last known value rather than the last know transition state.

Trigger: temperature < $threshold
  temperature = 100
  $threshold = 60

temperature = 58 → TRANSITION
temperature = 56 → (no change)
$threshold = 55
temperature = 54 → TRANSITION

So in that last example, even though the last transition state would have already been transitioned based on the original threshold, since the threshold changed, any new value would be compared against the last known value without any consideration for the last known transition state.

Edit: We’ve pushed an update which should support variables in the right side of a ‘Transition Only’ (changes) trigger. @Stephen_Boyle can you give it a try again?

[Stephen_Boyle]

woah! that was quick! ill take a look and see as it will trigger tonight for sure funny i was only using the variable because if i wanted to make a change i could do so in one spot as i tweak things - so even though it is a variable it will most likely never change. I can see how the logic on your end can get complicated with variables though. thanks!

[Stephen_Boyle]

@josh worked beautifully! no excess triggers! thanks