Concepts and Terminology
Reactor responds to changes in states of devices and object from the various HA systems to which it connects. It calls these objects entities. Entities have capabilities, which describe what attributes an entity has, and what actions it can perform. This is all you need to know for now, but there are many details about entities, capabilities, attributes and actions you should read about later as you use the system more.
Reactor evaluates rules that you define, which include responding to changes in the value of an entity's attributes. These changes trigger reactions, which are lists of actions to be performed in response the meeting the rule's requirements. Rules can include monitoring the state of multiple entities across multiple HA systems, and actions can be performed across multiple HA systems as well.
Rule sets in Reactor are just groups of rules. You determine what rule sets are needed, and what rules belong in those sets. Rule sets have no functional purpose other than to help you organize your rules. There are no operational limitations or side-effects to a rule being in one set or another, it's simply a visual/navigation aid for you.
Users of Vera will quickly realize that there are no "ReactorSensors" in Multi-system Reactor. A ReactorSensor in the Luup world served as a container for various related condition groups (rules), and was a necessary construction because all Luup plugins are related to at least one device. Rule sets are not device-based, but they serve a similar organizational function.
Triggers and Constraints in Rules
A rule has triggers, which are the tests that, when met, cause the rule to become set. When the trigger tests no longer succeed, the rule resets. There is a Reaction for each state, so you can set up a rule that performs some activity when its trigger conditions are met, and undoes the activity when they are no longer met.
A rule has an optional additional group of tests called constraints, and these are evaluated only when the rule is triggered (i.e. before it sets). The constraints are an additional set of conditions that are required to be met for the rule to set. Unlike triggers, changes in the conditions of constraints do not cause the rule to set or unset. They are only used as filter to allow or prevent the rule from setting. A common use case is a motion-sensor controlled light that you would want motion-sensitive only at night. The trigger conditions would supervise the state of the motion sensor, the set and reset reactions would turn the light on and off, and the constraints would ensure that motion detected would only allow the rule to set (turn on the light) when it is nighttime.
Constraints are new to Multi-hub Reactor. In Vera Reactor, you incorporated your constraints into your conditions. This sometimes meant you needed to do some extra work, like sequencing conditions, to make the example case above work correctly.
Reactions are collections of actions that Reactor can perform. There are two types of Reactions in Multi-system Reactor. Rule-based Reactions are the incorporated lists of actions to be performed when the rule sets or resets, one set of actions per state. These Reactions live are a part of their parent rule, and can only be run by the rule. Global Reactions are visible system-wide, and can be run by any other Reaction, rule-based or global. Their primary use is to encapsulate activities that may be performed by many rules.
Expressions are, as the name implies, expressions that perform some kind of computation and return a value. They are primarily intended to perform transformations on data that cannot otherwise be performed directly by a rule's conditions or a Reactions's actions. They are an advanced user feature, and most users will not need to use them. Like Reactions, there are two types: rule-based expressions and global expressions.
Navigating the Main Menu
When you first open a browser to your Reactor system's UI (at port 8111 by default), the system will display the Status view. The status view is a grid of selectable, configurable widgets that you can choose and arrange to show the overview information you most want to see. You can add, delete, resize, and rearrange these widgets at any time, and their arrangement is persistent on a per-browser basis (that is, you set arrangement sticks on your current browser, but does not affect the arrangements used on other browsers or systems).
The rule sets known to the system are displayed when you click the "Rule Sets" link in the left navigation area. The names of all defined rulesets will then be displayed under this link, and clicking any rule set name will cause the right side of the page to display the names of the rules in that rule set.
You can add a rule set by clicking the "circled plus" icon next to the "Rule Sets" label in the left navigation when rule sets are being displayed (the icon is removed in other contexts).
In the list of rules, clicking on a rule name opens that status card for that rule, so you can see what the states are of its trigger and constraint conditions.
The "Reactions" left navigation link presents a list of the global reactions defined in the system.
Expressions, like reactions, can be defined within a rule, or globally. When you click the "Expressions" link in the left navigation area, the page displays the global expressions currently defined. Global expressions, like global reactions, are usable in any rule.
The "Scope" link brings you to a tool that presents a simple "logic analyzer" view of entities and rules. On this page, you can choose a number of entities and rules, and their state will be graphed in real time. The intent of this tool is to allow you to visualize the relationship between changes to attributes on entities and the triggering of rules.
The "Entities" link in the left navigation brings you to the Entities List, a page that displays every entity known to the system. You may click on an entity name to see the capabilities that entity has, as well as the attributes and actions of those capabilities. The bold highlighted attribute, if present, is the entity's "primary attribute". This is typically the attribute that is most-often used to determine the entity's state. The actions available for the entity are links that you can click to run that action.
Get to know this view right away. It's very useful for looking at available attributes on a device, tracking changes in their value, and helping you write and debug your rules.
This page contains a number of helpful tools.
Actually, this page is empty at the moment, except for a single Restart button to restart Reactor.
The "Dashboard" link takes you to a simple grid view dashboard for all defined entities in the system. This dashboard is intended to provide a user-friendly way for your users to visualize and command the entities in the system.
If you're reading this, you know what the "Manual" link does.
The ubiquitous "About" link provides information about the Reactor version running, and some support and platform information that may be helpful in troubleshooting.
Other Changes for Vera Users
Reactor was originally written as a plugin for Vera home automation systems. Multi-system Reactor has much in common with Vera Reactor, and users moving from it to Multi-hub Reactor will quickly recognize the similarities, but there are also some differences:
- Multi-hub Reactor supports other HA platforms, like Home Assistant, Hubitat, etc., which Vera/Luup Reactor did not.
- Where Vera/Luup Reactor is very "device" centric, Multi-hub Reactor is "entity" centric.
- In the "tools" folder of the distribution package you will find an importer that can read Vera Reactor backup files and import their data into Multi-hub Reactor as rules. Not everything is done perfectly; there will still be work to do, but it's better than re-implementing every rule.
- Some Vera-specific condition types, such as geofencing and house mode tests, are not provided by Multi-hub Reactor, but their capabilities are available by other methods. Look for the "House Mode" and "Geofence" entities in the Entities List. These entities can be used in your rules.
- Values that are integer percentages on Vera (like dimming level) are 0.0 - 1.0 real numbers in Multi-hub Reactor.
- Resetting of latched conditions in Multi-hub Reactor is limited only to release by adjacent conditions (this was the original design of Vera Reactor that I regretfully drifted away from and decided not to repeat in Multi-hub Reactor).
New System, New Approaches
There will naturally be other timing and semantic differences between the two systems that may affect how your logic works. While it is absolutely a design goal to give you all of the functionality of Vera Reactor in Multi-hub Reactor, it is specifically not a goal of Multi-hub Reactor to operate completely identically.