[Reactor] [Dev] Clarifications/Docs for refreshCapabilities and Entity action implementations return types

[toggledbits]

MQTTController 23135

• In action payload, force conversion of all data types to string for "raw" output, rather than assuming result of expression is a string (although docs say to do that, it's just too easy to omit, and too easy to change it so the requirement is moot).
• Add parameter: name value form to action payload definition to draw payload value from the named parameter without the need to use an expression (this follows the implementation of action definitions in other Controller instances as well). That is, you can specify, for example, parameter: level instead of using expr: parameters.level (assuming the parameter value requires no scaling or other modifications to be compatible with the device). [docs]

[toggledbits]

Reactor Build 23171

NOTE: This build includes fixes made in a prior silent release (where the change(s) affected only one user).

DEPRECATION NOTICE: Support for versions of Home Assistant prior to 2022.5.3 will be removed on the next build. These older versions may continue to operate successfully with HassController going forward, but I will not address/fix issues for them.

• PR 0000356: Fix an issue where a rule with multiple sunrise/sunset conditions using the between operator chooses the first condition's before/after constraints rather than its own (i.e. it was choosing the control states from the first row rather than the current row).
• SystemController: the deprecated suninfo.sun_angle attribute is now removed (its replacement is suninfo.elevation).
• HubitatController: Hub variables can now be set up to 1024 characters with hub firmware 2.3.5.135 and above; for earlier firmware, the limit is 255 characters. The length limit is enforced by the hub, not HubitatController.
• HassController: Bless Hass to 2023.6.2

[toggledbits]

Reactor build 23196 (latest and stable branches)

NOTICE: As announced in the release note for the previous build (23171), Home Assistant versions earlier than 2022.5.3 are no longer supported.

• Introduce a maximum delay in the write-back of certain storage containers (e.g. that used for expressions).
• Docs: fix an error in an example on the How-To: Expressions with Entities page.
• HassController: Bless Hass to 2023.7.2

[toggledbits]

Reactor build 23218

• Improve the initialization of new global variables so they don't show "not yet evaluated" until a non-null value is set (null is a valid evaluation result and should remove the "not yet").
• Expressions: improve the display of non-printing characters in the expression editor's "current value" display (they now display as Unicode escape sequences).
• i18n: Fix init of localized weekday names when most recent Sunday occurs in prior month (caused, for example, incorrect weekday checkbox labels in Weekday conditions; cosmetic only, no operational effect).
• SystemController: for Reactor update, include update branch, version, and commit as attributes on system entity.
• Entities page: New Copy Attributes button in entity detail copies all attribute values to the clipboard.
• HassController: Bless Hass to 2023.8.0

[toggledbits]

Reactor Build 23242

• Rules Editor: Fixed an issue where a condition option change to the duration operator with no change to duration value may not be saved.
• HassController: Add mapping for proximity domain (to value_sensor).
• HassController: Bless Hass to 2023.8.2

[toggledbits]

ZWaveJSController build 23254

• Some versions of iBlinds v3 report CC 38 (Multilevel Switch) and some report 106 (Window Covering), no obvious way to tell if there's a config parameter that controls this, or if it's a firmware change (firmware versions report same even when command class is different). Update handles both based on what's available (this is the first time I've seen a 106-reporter in the wild).

[toggledbits]

MQTTController build 23254

• Improve recovery time when broker is starting up, accepts our connection, but then refuses subscription (i.e. it's not fully ready).

[toggledbits]

Reactor build 23302

• Expressions: functions asin(), acos(), atan(), and atan2(), and the reserved word pi (lowercase), are now supported (identical to their JavaScript equivalents).
• Update the documentation for migrating (importing) rules from Reactor for Vera (the Vera Reactor Plugin).
• HassController: All use of x_hass.call_service (the entity-based service call action) now uses the target field to specify the entity_id, rather than the old form which embedded the entity_id in the data field.
• HassController: The x_hass_system.call_service (system-global service call action) has been extended to allow the user to enter a target field for service calls that benefit from it. It should be noted, however, that the x_hass.call_service action on a Reactor entity (mapping a HA entity) should be used in preference to the system-global service call whenever possible, as changes in ID by HA will break the system-global call without warning (entity-based service call actions will simply use the new ID given by HA).
• HassController: Bless Hass to 2023.10.5

[toggledbits]

Reactor Build 23338

DEPRECATION WARNING (bare-metal installs only): all nodejs versions earlier than 18 are now end-of-life; these versions will not be supported for Reactor after 1-Mar-2024. You should upgrade nodejs as soon as possible. The minimum supported version is now 18.18, but for longevity, upgrading to the current LTS version is recommended. Users of Reactor running in docker containers are not affected, as the image always embeds a supported LTS version of nodejs (that is, no action is required for docker users).

• Expressions: Update lexpjs to fix degenerate case of case with single when and an else (which is better written as an if...then...else, but shouldn't throw an error in any case).
• CallMeBot: the built-in CallMeBot notifier is now deprecated. There are no plans to remove it right now, but it will not receive future updates. Use HTTP Request actions directly in Reactions instead.
• Reduce the frequency of reminder alerts when an upgrade is available.
• HassController: Bless Hass to 2023.11.3

[toggledbits]

Reactor Build 23344

This is a "silent" release (you won't get upgrade notices) and available for docker containers only at this time.

• PR 0000294: InfluxFeed now supports exporting of global variable values to InfluxDB. See docs.
• VirtualEntityController: Fix issue where a global variable dependency (value change) was detected, but the old GV value was always retrieved.
• Dashboard: Strings displayed by ValueSensor widgets are now elastic-sized to reduce overflow.
• Dashboard: Fix group spec handling so that custom top-level dashboards for a group can be created. This needs documentation.
• HassController: Bless Hass to 2023.12.1

[toggledbits]

Reactor Build 24052

BARE-METAL USERS: It is recommended that you update package dependencies when installing all Reactor updates. After unpacking the Reactor archive, remove any existing package-lock.json file from your Reactor install directory, and then run npm i --no-save --no-package-lock --omit dev to update package dependencies.

BREAKING CHANGE: The valve capability's state attribute value is now boolean, to match similar system capabilities (was previously/erroneously string). If you are using an entity with the valve capability in conditions or actions, make sure the type for the current or target state is boolean now.

• Update support for many packages. Please remember to do npm i --no-save --no-package-lock (bare-metal installs only; docker containers are always up-to-date).
• Add ability to override the state of a rule from the UI, for logic debugging purposes. A disabled rule will have its state forced, but will not run its reactions. An enabled rule will also have its state forced, but the corresponding rule reaction will run on the state transition. When overridden, the trigger and constraint conditions have no effect on the overall rule state, but (if rule enabled) are still evaluated and their status is still accurately displayed on the status card for the rule in the UI.
• PR 0000357: Implement getRule() extension function to get rule metadata; refer to the docs for more.
• Fix an error in the handling of the entity action cache in the UI (occurred when running actions from the entity detail in the Entities list).
• Docs: improvements to description of custom event handlers for HassController (still a work in progress, but isn't everything?).
• Docs: add a section in VeraController doc for the firmware's UnsafeLua flag, required to be on for the x_vera_sys.runlua action to be available. The value is now also published as an attribute on the system entity.
• HassController: Implement new HA valve domain with our valve capability.
• HassController: Bless Hass to 2024.2.2

MQTTController Build 24050

NOTE: Either 24049 or 24050 of MQTTController is required for Reactor 24052.

• Rebuild entity when configuration change detected (supports version field in user templates).
• PR 0000365: Fix broken config for tasmota_generic_relay template's toggle.toggle action.
• New templates for genmon (generator monitoring; see https://github.com/jgyates/genmon)
• Support for new js-yaml
• Support map in event handling configuration.

[toggledbits]

Reminder for Bare-Metal Installs

Friday, March 1 2024 is the last day for Reactor support on nodejs versions earlier than 18. The next build of Reactor releasing after March 1 will not operate on any earlier version. If you haven't upgraded your system to nodejs version 18 or higher, please read the earlier advisory for details and upgrade ASAP.

For the removal of doubt, builds 24052 (most recent build) and prior will continue to run on and after March 1 on earlier nodejs versions; there is not enforced stop on this date. It is only future builds that will refuse to start on out-of-date nodejs versions.

Docker images are always up-to-date and therefore this notice does not apply to them (no action required for docker users).

[toggledbits]

Reactor build 24057

NOTE (BARE-METAL ONLY): If you are upgrading to this build from a build earlier than 24052, please update your package dependencies. After unpacking the Reactor archive, remove any existing package-lock.json file from your Reactor install directory, and then run npm i --no-save --no-package-lock --omit dev to update package dependencies.

• PR 0000366: Fix an injection caused by the rule state override option added in 24052, which results in constraints on rules being handled incorrectly.

[toggledbits]

MQTTController build 24085

• Support for Shelly H&T Gen3 (use shelly_handt3 template and set topic). This is a battery-powered WiFi device, so its attributes will not be fully populated until the first wake-up.

[toggledbits]

Reactor build 24115

• Entities UI: When a capability filter is selected, the value column header displays a selector allowing the user to display a value in the column other than the primary value for the filtered entities.
• The extensions subdirectory ext may now be located under config, which makes its location uniform for bare-metal and docker users; this will eventually become the standard location. It is not necessary at this time to relocate your existing ext directory if you have one — either or both the old and new locations will work for the foreseeable future.
• Improve the coordination of the Reactions and Rules displays when open and interacting on multiple displays (e.g. when you delete a reaction on one screen, it should disappear from the other(s)).
• Fix a browser-side performance issue/delay with reconnection to a restarting Reactor service when the Status page is up and displaying the Recently Changed Entities widget. This also improves the memory consumption and performance of the widget generally.
• Increase tolerance for damage to most storage objects, particularly those that only maintain state that can usually be safely rebuilt on the fly. For those that cannot, like rules and expressions, isolate a faulty file and ignore the object with an alert to the user. Preserve the broken file.
• PR 0000367 Localization of the new strings in the rule state override menu and state display have been added.
• PR 0000368 Fix missing localization string for Copy Attributes button in Entities list entity detail card.
• Report detected time zone and offset in startup messages. Add time zone display to hover title on browser and host times in UI header.
• New wifi_status system capability for WiFi-connected devices that can report connection status.
• PR 0000369 Docs: Add documentation for ev_charger system capability.
• HassController now supports responses from services that support them; whether required or optional, a response will be requested and stored in x_hass.last_response on the target Reactor entity. The data returned is not processed in any way; it is written as-received to the attribute. Tip: if possible, always make the service call from the target entity, not from the system entity.
• HassController: Bless Hass to 2024.4.4

MQTTController 24114

NOTE: This version requires Reactor build 24115 or higher

• Add template for Shelly RGBW2 (using Gen1 API) called shelly_rgbw2_color (requires topic).
• Add support for wifi_status capability for some devices; more to come. Previously, those devices stored WiFi status info in x_mqtt_device (extended capability) attributes. Now that a first-class capability is being used, the extended attributes are deprecated and will be removed from a future release.
• Templates may now remove an action from an entity if it isn't supported by the device. This is done by specifying the action's value as false. If a device cannot support any action of a capability, the entire default list of actions for the capability can be removed by specifying the capability value as false in the actions section of the template. For an example, see the template shelly_rgbw2_color implementation for capability light_effect action set_speed, and the action implementation for the button capability.
• Templates may now define custom actions in x_mqtt_device. Including an arguments object in the standard action arguments format allows the template to notify the UI of the arguments required by the action. For an example, see the template shelly_rgbw2_color action x_mqtt_device.set_white.

[toggledbits]

MQTTController 24120

• Soft reconfiguration of entities on configuration changes and system upgrades. This should preserve attribute values when the entity needs to be configured due to implementation changes for capabilities.

[toggledbits]

MQTTController 24142

DEPRECATION NOTICE: The uses_template entity configuration directive is now deprecated; use include instead (see below). It will remain functional until build 25091 (Q2 2025).

• PR 0000370: Events for tasmota_generic_relay in template have hard-coded device ID (left over from test/dev).
• System templates are now broken up to multiple files in a hierarchy within the templates distribution subdirectory.
• New include directive in entity configuration or a template can be used to include the data of another template. You may name a single template (string value), or an array of template names. This permits common behaviors across devices to be modularized in templates. This directive also now replaces uses_template, which is deprecated (see above notice).
• The user custom template directory (config/mqtt_templates/) now supports any directory hierarchy the user wishes to maintain within it. It searches for templates in YAML or JSON files in the hierarchy, and will traverse ZIP files as well (so template developers can distribute their products in ZIP archives for easy installation/upgrade).

[toggledbits]

Reactor build 24152

POTENTIAL BREAKING CHANGE: The port on which Reactor provides HTTP(S) service is now determined by the baseurl configuration value first. If no port is given there, the PORT environment variable is then queried; if that's not set, the default port is used (different for HTTP and HTTPS; see below). In previous versions, the PORT environment variable had the highest priority, but this is no longer the case. This will likely have no effect on most users, but if you're having trouble accessing the UI after upgrade, check your baseurl configuration first (if you don't have one or need an example, refer to the distribution version of reactor.yaml in dist-config. For users using Reactor via HTTPS (SSL/TLS encryption), I recommend using port 8554 in baseurl; regular HTTP (no encryption) remains on port 8111.

• User Authentication and Access Control. See the Access Control documentation. This is feature request PR 0000351.
• The default port for HTTPS-enabled Reactor is now 8554 (8111+443). If your system or docker configuration set the PORT environment variable before starting Reactor, whatever port that specifies will be used as before. See the How-To: HTTPS section of the documentation for information about configuring Reactor for HTTPS.
• The port used for HTTP(S) service is now determined by the port specified in baseurl (in config/reactor.yaml) first; if no port is specified in baseurl, the PORT environment variable is used if set, and finally the Reactor default of 8111 (or 8554 if TLS is enabled).
• If HTTPS (HTTP + SSL/TLS) is enabled and its configured port is other than 8111 (the standard HTTP (non-SSL/TLS) port for Reactor), an HTTP service on port 8111 will now be created to redirect requests from HTTP to HTTPS (no unencrypted service is provided other than redirection). This feature can be disabled by configuring redirect_http to false in the reactor section of config/reactor.yaml.
• The allow_ips in the reactor section of config/reactor.yaml now allows CIDR address range specification (e.g. 10/8 or 192.168.0/24) for ranges of addresses.
• Updated the documentation theme and its supporting plugins; improved the appearance of code snippets with syntax highlighting in most cases; add line highlighting in many code snippets to draw attention to certain elements or changes.
• Dashboard: added new Thermostat type (supported by Level.updown layout) for capabilities hvac_heating_unit/hvac_cooling_unit. Evolving; further improvements coming.
• VirtualEntityController: Support for time-series data collection and aggregation. See the docs).
• VirtualEntityController: Preserve attribute values if possible across system updates that affect capability definitions or implementations.
• DynamicGroupController: It is now possible to set the primary attribute of a dynamic group, and determine its value dynamically. Trivial example: add the binary_sensor.state attribute to a group to show true when any light in the group is on. Refer to the docs for DynamicGroupController.
• The dist-config directory is now copied to the user data virtual path target when running in docker containers so that its contents are more easily accessible to docker users (no need to docker exec into the running container).
• Rules: the logging level for most rule evaluation messages has been reduced to DEBUG0 (numeric level 5); rules will now log only startup/shutdown and rule state changes at INFO level. Per-object logging configuration can be used to enable more detailed logging for a specific rule when required.
• Fixed an issue in the core related to deleting certain objects (a Global Reaction was reported, but could have been many object types).
• Fixed an issue with local service of docs that caused a cross-site scripting error on some browsers (this is the "Initializing search..." bug).
• Developer Tools: the util function deepCompare() now works with JavaScript Set, Map, Buffer, and RegExp objects.
• Developer Tools: documented util function hash() (it's been around a while, just not documented).
• HassController: Bless Hass to 2024.5.5

[toggledbits]

MQTTController build 24155

NOTE: This build contains only compatibility changes; no bug fixes or new features.

• Small change to preserve compatibility with older builds of Reactor; this in particular is to ensure that users of the stable release branch are able to use the latest version of this controller.

[toggledbits]

Reactor STABLE Update

The stable branch of Reactor is now updated to build 24057. For changes, please scroll back and see the changes and advisory listed since the previous stable branch build (which was 23344).

IMPORTANT: Bare-metal users will need to update installed packages (see note here) and be aware of the breaking change notification (same link).

NOTE: This will be the last stable branch release that supports versions of nodejs < 18. If you haven't yet upgraded nodejs on your system, you will need to do so before the next stable update (an even-numbered LTS version is recommended). This applies to bare-metal users only; docker users have compatible versions of nodejs built into the Reactor distribution image.