New App Features in 2.2.8

Release 2.2.8 introduces a number of new features, new apps, and new app features. These include Hub Variables, a new version of Rule Machine, Rule 5.0, Button Controller 5.0, and Button Rule 5.0.

Hub Variables

We have added Hub Variables as a Setting for the hub. Hub Variables are quite similar to Global Variables in Rule Machine, but implemented in the hub rather than in the RM parent app. This provides for the use of Hub Variables in other apps, not just in RM. Hub Variables are very efficient, being implemented directly in the hub.

Hub Variables are one of five types: Number, Decimal, String, Boolean and DateTime. We have extended the Time type of variable to DateTime, allowing both time and date to be set. The use of date has very limited applicability for now, specifically in the Certain Time trigger for Rule 5.0, where triggering on a specific date is possible; by using a DateTime connector, that can be a variable Date and Time.

Each Hub Variable can have an associated Connector. A Connector is a virtual device linked to the Hub Variable. When the Hub Variable value changes, so does the Connector value, and vice versa. When the Connector device is set to a different value, the corresponding Hub Variable is set to that value. Connectors can be used in any app.

The UI for managing Hub Variables can be found in Settings. This allows for the creation of a Hub Variable, changing its value, creating a Connector for it, and removing it. If a Hub Variable is in use by an app, the name of the Hub Variable is shown in orange, and clicking that shows the apps it is in use by. When a Connector is created, the type of Connector is shown in blue, and clicking that opens a new tab with the Connector device page. The value of the variable can be changed by clicking on the purple text in the Value column. When a Connector exists, the variable value is shown with the selected attribute for the Connector. For example, a Boolean variable for which a Switch Connector is created, will show "on" or "off" as the possible values, instead of "true" and "false".

To remove a Connector, open the device page for the Connector and remove it from that page. If the Connector is in use by any apps, be sure to clean up those apps first; the warning to do so is presented to prevent mistakes.

To remove a Hub Variable, click on Delete for that variable. If the variable is in use by an app, an appropriate warning will be provided, and those apps should be cleaned up before deleting the Hub Variable.

Rule Machine

There is a new version of the main Rule Machine parent app. In order to transition to Hub Variables it is necessary to introduce this new parent app, as the former parent app incorporates support for Global Variables, which are replaced by Hub Variables going forward. Due to the need for ongoing backwards compatibility with existing rules, it is a requirement that the older version of Rule Machine not be changed with respect to Global Variables. Thus, the new parent app is introduced in 2.2.8. The older parent is now called Rule Machine Legacy. We've learned that it is better to have less rather than more functionality in a major parent app such as Rule Machine. This is one of the motivations behind moving away from Global Variables., as well as improving variable performance with Hub Variables supported directly by the hub system.

Rule Machine remains the means going forward to create new rules, and those rules will be Rule 5.0 (see below). All existing instances of Rule-4.1 will continue to function, and there is no need to convert these rules to Rule 5.0. Rule Machine Legacy will continue to be available until release 2.2.9, so in the interim it is possible to create either Rule-4.1 rules or Rule 5.0 rules. We encourage you to move to using the new Rule Machine and Rule 5.0 going forward.

Rule 5.0

There are a number of improvements in Rule 5.0 relative to Rule-4.1. These include Predicate Conditions, Hub and Local Variable usage, and Wait for Conditions for Duration.

Predicate Conditions

There is a new option to define Predicate Conditions — essentially a logical expression like any other in rules. When defined, the rule will only be triggered if the Predicate Conditions are true. Subscriptions are made to the devices used in Predicate Conditions, so the truth is updated as the devices and other conditions change state. Predicate Conditions are based on the state of the selected conditions before an event triggers the rule. An event triggering a rule therefore does not change the truthfulness of the Predicate Conditions as pertain to that triggering of the rule. The truthfulness of the Predicate Conditions is again established after the rule has run, if it does run.

Predicate Conditions have two main uses: First is to restrict a rule to only run when certain conditions are true. As such, a wide variety of custom restrictions can be used. Second is to implement state transition based rules. If an initial state for such a transition is set as the Predicate Conditions, then a trigger that realizes the transition can fire, but only when that initial state is in true, in other words, the rule only runs for the intended state transition.

As an example, suppose we want a rule that runs when the mode changes from Away to Evening. A regular trigger on Mode becomes Evening would fire whenever the mode becomes Evening. But we want the rule to only fire if mode is Away, and then becomes Evening. The Predicate Condition is Mode is Away, and the trigger event is Mode becomes Evening. This rule below realizes this particular state transition:

When the Predicate Conditions are found to be false, trigger subscriptions and scheduled jobs are suspended until the Predicate Conditions become true again. Even if these events were to fire, the rule would not run its actions if the Predicate Conditions are not true at the time immediately before the triggering event.

Hub Variables and Local Variables

Whereas the prior version of Rule Machine supported Global Variables, in the new Rule Machine and Rule 5.0 these are replaced by the hub system-native Hub Variables. Hub Variables offer the same functionality that Global Variables did in previous versions. Rule 5.0 also retains the option of Local Variables. The primary reason for Local Variables is that the scope of variable names is local to the specific rule in which they are defined. Should there be a Hub Variable of the same name as a Local Variable, the Local Variable prevails within the rule that defines it. Otherwise, the functionality of Hub Variables and Local Variables is almost identical to previous versions (see below for changes). Performance of each type of variable should be comparable, without large overheads as was sometimes the case with Global Variables.

Variable usage in actions

Where variables can be used in actions, there are explicit options to do so. The previous use of %variable-name% in an input setting remains only for use in strings inputs for actions. Primarily this would be used in Send Message type actions, or setting a variable where the source input is a string. In all other cases, the use of %something% in value inputs has been eliminated in favor of explicit selection of variables.

Variables as triggers

In previous versions of Rule, a Global Variable could be used as a trigger. This is no longer supported as such. However, any variable connector can be used as a trigger to accomplish the same result. Connectors can be used in other apps, including Dashboards, to represent a variable and read or set its value.

Wait for Conditions for Duration

A new option for Wait for Conditions is to select a duration of time. Wait for Conditions has an option to select a timeout period. If the Conditions don’t become true prior to the timeout expiring, the Wait is over upon the timeout expiration. The duration option is different: The duration option specifies an amount of time that the Conditions must remain continously true for the Wait to conclude.

Wait for Conditions with duration is useful for many automations that require the passage of some time in a certain state. For example, suppose we want to send a notification if a door has been left open for more than 5 minutes. This rule could be triggered by the door opening, and than have a Wait for Conditions that the door is open for a duration of 5 minutes, Following the Wait, we’d have the notification action. If the door is closed before 5 minutes are up, the Wait will not conclude. If the door opens again, as with all Waits the pending Wait is canceled, and a new one begins. Only if the door is opened and remains open for 5 minutes will the Wait conclude, and the notification be sent.

Wait for Conditions allows a fulll logical expression. It is possible that during the wait period events may occur that affect the Conditions, but do not alter their truthfulness. In these cases the waiting continues, the clock still running, so to speak. But, on the other hand, if an event occurs that renders the Conditions false, the clock is stopped, and the waiting for the conditions to become true ensues. Should the Conditions become true again, the clock will start over, waiting for the full duration to run before the Wait concludes.

In the case where the rule’s trigger event is closely related to the Conditions, as for example in the case above about the door remaining open, please note that two subscriptions will fire, one for the trigger, and one for the pending wait. The trigger will win out, canceling the pending wait, but if logging is on, both outcomes of the event will show in the logs. N.B. It is important never to use a changed trigger with a Wait for Conditions on a related event. If this is done, the rule will retrigger on every event related to the Conditions, and the Wait will never conclude since the Wait is cancelled by the trigger.

Removal of embedded Button Controller functionality from Rule

The previous trigger type of ‘Button device’ has been removed from Rule 5.0. This trigger selection opened a page allowing basically the same functionality as Button Controller within a rule. This embedded form of Button Controller allowed for the full advanced action functionality of Rule-4.1, far exceeding the functionality of Button Controller 3.1. In its place there is a new version of Button Controller that has this functionality (see below).

Device Event Description Text

The description text sent with most device events can be retrieved in a rule using %text%. This description text could be put in a String variable, and then inspected for a specific value.

House Keeping and Shared Conditions

One issue that came up frequently for Rule-4.1 and prior versions was that often after editing a rule a device that at one time was used by that rule, but was no longer, would show as still In Use By that rule. Rule 5.0 does a better job at this sort of housekeeping.

However, there is one issue that arises from this housekeeping to be aware of: If a condition is used in more than one action in a rule, or between the Predicate Conditions and a Conditional action (a shared condition), and you delete one of these actions, the condition will be deleted along with it. This will break other references to the shared condition, as it no longer exists. So use shared conditions carefully, and only if you're sure you don't plan to delete the actions they are used in.

Button Controller 5.0 and Button Rule 5.0

A new version of Button Controller is now released in 2.2.8. This version replaces both the older Button Controller 3.1, and the previous embedded version of Button Controller functionality in Rule-4.1 as the ‘Button device’ trigger. Each button's actions for Button Controller 5.0 is its own rule, called Button Rule 5.0.

Button Rule 5.0 shares the same code base as Rule 5.0, and offers all of the same functionality for actions with one notable exception: Button Rule 5.0 does not offer Local Variables. It does allow use of Hub Variables.

Each specific button’s actions, an instance of Button Rule 5.0, is a ‘grandchild’ app of Button Controllers, and a child app of the Button Controller 5.0 for that button device. This makes each button’s actions more efficient as a stand-alone app.

Button Controllers does not yet support export/import or cloning of Button Controller 5.0 / Button Rule 5.0 apps. We hope to support this feature in a future release. In 2.2.8 we have introduced a new structure: grandchildren apps (Button Rule 5.0 is the first and only such), and we need to make some further platform improvements to support export/import/clone for them.

Prior Versions

As is the norm for new app releases, the prior releases of Rule Machine Legacy, Rule-4.1, and Button Controller-3.1 will continue to work without modification. There is no need to replace existing automations. If you have Rule Machine Legacy installed, you will be able to continue to create Rule-4.1 automations until Release 2.2.9. Even after its 'retirement', existing Rule-4.1 instances will continue to work, and it will be possible to edit/export/import and clone them. We encourage you to check out the new Rule Machine, Rule 5.0, and Button Controller 5.0, as these releases represent significant improvements over prior versions.

Do not attempt to import Rule-4.1 rules into Rule Machine, only into Rule Machine Legacy. This is not supported and will throw an error. Rule 5.0 has no backwards compatibility to Rule-4.1.

28 Likes

This great stuff here. I would like to see if you could back up the 4.0/4.1 rules and the import them back into 5.0 as a way convert easily. I do see that this doesn't work but this may be a way to move things forward more rapidly. Thank you for your time.

2 Likes

No, this really is not possible. The backup of a rule reflects the internals of the app (e.g., Rule-4.1). Under the covers, Rule 5.0 has been rewritten in many areas to make it more efficient. So while it looks mostly like Rule-4.1 on the outside, it actually is very different on the inside. An attempt to map from 4.1 to 5.0 would be a difficult to impossible task, a huge undertaking. So, that's not going to happen.

Having said that, there is no reason to move an existing working rule from 4.0/4,1 to 5.0. If it isn't broken, don't fix it! If you want to change the rule to use new features, make a new rule. I still have working rules from all prior versions of Rule, dating back 4 years. Once in a while I'll look at an old one, and once in a while I'll redo it -- but they work, so there is no need to do anything.

10 Likes

Some of us just don't like rewriting rules.... :slight_smile:

Screen Shot 2021-07-15 at 12.55.51 PM

17 Likes

Is anyone else getting Button Controller errors since the 2.2.8 update?

Yes. There's also an error in logs:

org.codehaus.groovy.runtime.InvokerInvocationException: hubitat.exception.NotFoundException: Child app not found for namespace: hubitat and name: Button Rule-5.0 on line 68 (mainPage)

I had the same issue. I removed the application and rebooted and re-installed it again. that worked after that.

How do you get the error, i.e. what are the steps to reproduce it? I see there's an app instance of Button Controller-5.0 on the hub, and things generally look ok at a first glance.

I suspect reboot may be a key part of a solution here. @dthompson10 and @jsarcone, could you please try rebooting the hub and see if that gets rid of the error?

1 Like

Rule 5.0 sounds very similar to Rule 3.0 bringing back Conditions.

Not really, only superficially. The BIG difference of Predicate Conditions is that they are set before the rule is triggered. With Rule-3.0, a Condition was tested when the rule was triggered by anything happening that would affect the rule, and then actions for true and false followed. For a Predicate Condition, nothing happens because of it changing from true to false or false to true -- that does not cause actions to run.

That's why they are called "Predicate Conditions". These conditions must already be true for the rule to be triggered.

5 Likes

Thanks, the error has gone after a reboot :+1:

2 Likes

(I haven't updated yet so asking before updating) but I'm assuming the above statement also means that the predicate conditions only apply to the rule being "true" and not having them to also run the rule based on the predicate condition being "false" as well like RM 3.0 could do. If so this would be a big difference as well.

The error is gone after deleting my 3.1 instance of Button Controllers, rebooting, and installing the 5.0 instance.

Right. Nothing runs because of changes to the Predicate Conditions, neither for true or false.

The easiest way to wrap your head around this is to think about restrictions: "Only run this rule if its Wednesday". A restriction in 3.0 wouldn't in and of itself cause anything to happen, it just was a pre-condition that had to be true for the rule to run at all. Predicate Condition = Pre-Condition. When it became Wednesday, the rule wouldn't say "Restricted" anymore, and it would run whenever it was supposed to run -- but it didn't run when the day changed from Tuesday to Wednesday. You will see something similar with Predicate Conditions: if they are false, the rule will show "Predicate Condition False" -- meaning, it isn't going to run.

As it says in the writeup above, Predicate Conditions are essentially Restrictions on steroids. They have other uses too, but that's probably the easiest way to explain how they function.

6 Likes

Just came here to say this is awesome! Didn't fully realize what this was until I updated and see the libraries code section. Now I can take some of the common stuff from my drivers that works really well and combine it for not only easier updates but also to share as a library for others to build drivers off of.

image

3 Likes

I did after a removal.. reboot Re-install. no reboot after that. I worked for me.

2 posts were merged into an existing topic: How to use library code

Wow. This is an incredible jump.

3 Likes

3 posts were merged into an existing topic: How to use library code

I'm certainly in no position to quibble about how it works under the hood, but from a user perspective, it seems like what was old is new again.

From 2016;

Not that I'm complaining. I missed conditions. (Will we be revisiting Rule Truth again? )

Thanks @bravenel

Download the Hubitat app