homebridge-mq77-customizer 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,323 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## [1.5.0] - 2026-08-27
+
+The first public release, on npm.
+
+### Added
+
+- The web interface says plainly that it belongs on your own network: anybody past its one password can switch every device it publishes
+
+### Changed
+
+- Installed from npm, the way any Homebridge plugin is installed
+
+## [1.4.1] - 2026-08-27
+
+### Changed
+
+- Installing the plugin no longer asks for `sudo`, which `hb-service add` does not need
+
+### Fixed
+
+- The build's progress messages go to stderr rather than stdout, so anything reading `npm pack --json` gets JSON and nothing else
+
+## [1.4.0] - 2026-08-27
+
+### Added
+
+- A device panel says under Diagnostics whether the broker keeps that device's messages, read from Zigbee2MQTT's own configuration, and the timestamp the device last reported for itself
+- Test builds and releases are built on GitHub and published as an installable tarball, so a Raspberry Pi installs what GitHub compiled rather than compiling it itself
+
+### Changed
+
+- When a device was last heard now comes from the device rather than from this plugin, which no longer keeps arrival times of its own. Zigbee2MQTT publishes it once `advanced.last_seen` is turned on; a device that publishes none shows none, since a retained message replayed on connect says nothing about when the device spoke
+- What a device is and the topic it lives on move off the card header onto the first line of the open panel, so the header reads as the name, when it was last heard, and what it became in HomeKit
+- A device's functions are listed by name within Functions, Settings and Diagnostics, and the tile picker is called what it chooses: the HomeKit tile
+- The README says what the settings are for and leaves naming them to the settings form, which describes its own fields more clearly. Installation is the command any plugin is installed with
+
+## [1.3.0] - 2026-08-25
+
+### Added
+
+- A Cycle button for sliders: one button for the whole range, stepping up to the top, back down to off, and up again. It starts upward whenever the level was last set by something else, and ignores a second press within a second, unlike the stepping buttons
+
+### Changed
+
+- The tabs become a dropdown below 960px rather than below 640px, aligned left with the Zigbee2MQTT link still at the end of the line. The Map is in the dropdown now, since a window that narrow can still draw one
+- The Controllers tab draws two tables side by side where there is room, marks where one physical button gives way to the next, and drops the `Button | Action` heading row, which said what the two columns say themselves. `controller-config.md` keeps its heading, since a markdown table cannot do without one
+
+### Fixed
+
+- The Clear button is back on the Activity tab, at the end of the line above the log. It was removed altogether when it should only have stood down on a phone, which is what it does now
+
+## [1.2.0] - 2026-08-25
+
+### Added
+
+- The Controllers tab says `In HomeKit` of a button whose press reaches HomeKit, in place of `none` where no rule answers it and underneath the rules where one does
+- A HomeKit buttons tick in the header, beside Unused buttons, says whether those lines are wanted. With both down a button nothing answers is left out entirely, in the tables and in `controller-config.md` alike
+
+## [1.1.0] - 2026-08-25
+
+### Added
+
+- A Controllers tab, listing every button of every remote and what it sets off. Buttons nothing answers read as `none` and can be hidden, and the whole overview downloads as `controller-config.md` to keep beside the remote
+
+### Changed
+
+- A press and the rule it sets off read as one line in the activity log, `Woonkamer Remote 4 Single Long → Woonkamer: All Off - ran: 2 actions sent`. Presses that set nothing off keep a line of their own, and start hidden
+- Actions read as buttons in the activity log too, `4 Single Long` rather than `4_single_long`
+- A slider says what it did in the words somebody would use: `Brightness+ 1/6`, `Brightness- 0/6 (off)`, `On to Brightness 94`
+- A mirror says which function it read and which it wrote: `Gang Voor State → Gang Achter State`
+- A rule with more than one outcome says which one ran, in quotes
+- Held back and nothing to do both read as `ignored`, and a timer called off says so without repeating why
+- On a phone a log line stacks into what set it off, which rule, and what it did
+
+## [1.0.0] - 2026-08-24
+
+### Added
+
+- Settings can be downloaded and uploaded from the footer, which is the only copy that survives losing the machine
+- The last ten dated copies of the settings are kept in a `backups` folder, one at startup and at most one an hour after that, and one can be taken on the spot from the footer
+- A device that carries the same function more than once, such as a three gang switch, can put every channel into a mirror instead of one of them
+
+### Changed
+
+- A remote's actions read as buttons, `1 Single Long` rather than `1_single_long`, and are listed in the order somebody would read them out
+- Picking what sets a rule off marks with a `*` any value already used by another automation, slider or timer, so two rules do not end up on one button press by accident
+- A rule just added stays at the top of the list until it is saved, including when the list is grouped by room, and has no enabled switch until then
+- The footer reads left to right: which build this is, what the settings are doing, and the way out. It says when the last copy was taken and stacks onto two lines on a phone
+- Descriptions break after the arrow rather than in the middle of what follows it, in rule lines and in the activity log
+- Rule lists redraw far quicker, most of all when grouped by room. A panel is built when it is opened rather than for every rule in the list, sort keys are worked out once rather than inside every comparison, and devices are looked up by name rather than by walking the list
+- A settings file that cannot be used says so in a dialog rather than in the corner of the header
+
+### Fixed
+
+- A run that starts with nothing refuses to write over a settings file that has something in it, and says so
+
+## [0.16.1] - 2026-08-24
+
+### Fixed
+
+- Adding a device to a mirror did nothing. The function rows were redrawn with the new device in them, but the group behind them was only written back when something was clicked, so saving sent the members it had before
+- Taking devices away until one was left kept a group of one, which mirrors nothing. The save was then refused for a reason nothing on the screen explained, since the row had already gone
+
+## [0.16.0] - 2026-08-24
+
+### Changed
+
+- Signing out and the build label move to a footer at the foot of the page, and how the connection is doing becomes a word beside the title, green when live
+- Switching a rule on or off is a tick box in its header, saved as it is clicked. It writes the stored rule with one thing changed, so turning something off does not push half written panel edits out with it
+- The "In HomeKit only" and "Enabled only" filters are gone: a rule switched off is still a rule you are looking for
+- The activity log reads as three columns with room to breathe, so every description starts in the same place, and can be emptied
+- The add buttons read "+ automation", "+ outcome" and the like, and each tab's description says what it is for in one line
+- Inputs and selects state their height, since the same padding on both left them a few pixels apart on one row
+
+## [0.15.0] - 2026-08-23
+
+### Added
+
+- A Timers tab waits between one thing and another: a light coming on, thirty seconds, the light going out again. The clock starts again if the same thing happens again, and is called off the moment what started it stops being so, which an automation with a delayed action cannot do. A timer counting when Homebridge restarts is forgotten
+- An automation or a timer can be run by hand from its panel, switched on or not, once it has been saved. The conditions still hold sway, and the button is absent while the panel and the stored rule disagree
+
+## [0.14.0] - 2026-08-23
+
+### Added
+
+- Every device takes a name, a room and a kind of its own, set in its panel. They are for the interface: HomeKit keeps rooms in the Home app, where no accessory can set or read them. The name reaches HomeKit only where the source names nothing itself
+- Eight kinds, each drawing an icon: Light, Sensor, Controller, Fan, TV, Audio device, Media device and Other
+- The device list sorts into groups by room or by kind, and the rule lists by room, meaning the rooms a rule acts in. A rule reaching two rooms is listed under both
+- Button presses from a device marked as a Controller appear in the Activity tab, with a filter of their own
+
+### Changed
+
+- A rule is named by the rooms it acts in rather than the room it is set off from: "Study: Nightlight toggle". The rooms come off only under a heading that has said all of them
+- The line under a rule's name names devices and counts the rest, rather than spelling out which function of each it writes
+- Under a room heading a device from another room keeps its room in its name, since which one it is still matters
+- The activity log reads as a sentence, with the outcome and then what happened, and names devices the way every other list does
+- Automation triggers and slider buttons are no longer joined by "or"
+- The pencil rename button is gone: the name is one of the three fields now, and offered on every device
+- Mirror and slider lists sort by name or room only
+
+## [0.13.0] - 2026-08-23
+
+### Added
+
+- A Sliders tab drives a dimmer or a fan from buttons. The level is cut into steps and a press moves it one step, which as automations would be four to six rules that only make sense together. Either button switches the device on when it is off: step up goes to the level the device itself keeps, step down to the bottom of the range. Step down from the first step switches it off rather than leaving a light at zero brightness and still on
+- Each slider button takes several triggers, so one slider can be driven by more than one remote
+
+### Changed
+
+- Delete on a rule sits at the far end of the footer, is red, and asks once before deleting anything that has been saved, going back to asking after two seconds. A rule only just added still goes on the first click
+
+### Fixed
+
+- A rule just added disappeared when the list was filtered, or when "Enabled only" was ticked, since it is saved the moment it is added and so starts with a placeholder name and switched off
+
+## [0.12.0] - 2026-08-22
+
+### Added
+
+- A Map tab draws the Zigbee network: the hub on the left and a column per hop out from it, so what reaches it directly and what goes through something else can be read down the page. Every link found is drawn, with the route each device uses picked out, and clicking a device says what it can hear and how well. A device the scan found but nothing connects to is drawn dashed rather than left out
+- Automations sorted by trigger are listed under the device that sets them off, one line per trigger, so a remote with six buttons reads as six lines. A rule with several triggers appears under each of them
+
+### Changed
+
+- An outcome is called what it was named in the activity log, falling back to its number
+- A rule just added stays at the top of its list until it is saved, rather than sorting under a name nobody has chosen yet
+- Sorting automations by target device is gone
+- Mirror device selection runs down three columns instead of wrapping across the page
+- Described devices sit behind a collapsed panel in the config form, with Rules only moved up under ID
+
+### Fixed
+
+- A child lock ticked on a socket showed nothing in the Home app. HomeKit allows a physical lock on its air services only, so on anything but a fan the lock now gets a switch of its own
+- Every healthy router was reported as having failed the network scan, since an empty list of unanswered requests reads as true
+- A tick box in the mirror editor was stretched to the width of a value box
+
+## [0.11.0] - 2026-08-22
+
+### Added
+
+- A flat JSON source can describe functions a device has but never reports, such as the speed and swing of a fan. What was described is logged at startup, and a described topic nothing reports on is named in a warning alongside the topics that did
+- Outcomes can be named, beside a remove button that is now a plain cross
+
+### Changed
+
+- The automation editor keeps "or", "and" and the buttons that add another on the row they belong to, instead of each on a line of its own
+- Remove group sits at the top right of its box
+- Outcomes are spaced apart and faintly shaded
+- Rule rows have fixed widths, so the columns line up from one row to the next
+- Number inputs are styled like every other input instead of unstyled, which is what made the delay box look out of place
+- In the config form, described devices sit behind a collapsed panel and Rules only moved up under ID
+
+### Fixed
+
+- Sorting and filtering on the Automation and Mirror tabs, which threw on any rule saved since outcomes arrived and emptied both tabs without saying why
+- The device picker in a rule was styled as a device card, since it shared its class
+
+## [0.10.0] - 2026-08-21
+
+### Changed
+
+- The broker is configured as one address, `localhost:1883`, instead of a separate host and port. The port may be left off. A host and port stored separately are still read, so an existing install keeps its broker
+- Broker username and password only appear once "Requires authentication" is ticked, and are ignored when it is not
+
+## [0.9.1] - 2026-08-20
+
+### Fixed
+
+- Accessories are no longer dropped and re-added on every start. The catalog is empty before the broker answers because nothing has arrived, not because there is nothing, and removing an accessory makes HomeKit forget which room it is in
+
+## [0.9.0] - 2026-08-20
+
+### Added
+
+- A rule can have several outcomes, each a condition and its own actions. The first that holds runs and the rest are skipped, which is if, else if and else
+- Any outcome may be left without a condition, meaning it always holds
+- The activity list says which outcome ran, and what each wanted when none did
+
+## [0.8.0] - 2026-08-20
+
+### Added
+
+- Conditions are an expression: groups joined by or, tests within a group joined by and, and any group can be negated
+- A rule can have several triggers, any of which fires it
+- The interface header shows the version on a released build, or the branch it was built from on any other
+
+### Changed
+
+- Failing an or reports what every branch had against it, rather than only the first
+
+## [0.7.0] - 2026-08-20
+
+### Added
+
+- Activity is its own tab, listing both kinds of rule with each entry saying which it came from
+- Each tab offers the controls that suit it: In HomeKit only on Devices, Enabled only on the rule tabs, a checkbox per kind on Activity
+- Rule lists can be ordered by name, or by the first device on either side, and filtered by the devices a rule touches as well as its name
+
+### Changed
+
+- Automation and mirrored devices are separate tabs rather than one list behind a checkbox
+- Filters and orderings are kept per tab
+
+## [0.6.1] - 2026-08-19
+
+### Added
+
+- Optional link to the Zigbee2MQTT interface in the tab bar, set with `web.zigbee2mqttUrl`
+
+## [0.6.0] - 2026-08-19
+
+### Added
+
+- Sort the device list by name, topic, device or when it was last heard from
+
+### Changed
+
+- Device pickers in rules are always ordered by name, whatever the device list is sorted by
+
+## [0.5.0] - 2026-08-19
+
+### Added
+
+- Rules engine: when something happens on one device, send something to another, across sources
+- Triggers, optional conditions and one or more actions, with optional delays
+- An action can send a fixed value or match whatever triggered the rule, translated into the target's terms
+- Mirror rules: pick devices and the functions to keep in step, every member both trigger and target
+- Rule editor and a run log in the web interface
+- Devices whose source does not name them can be renamed, from a pencil in the card header
+- Show when a device was last heard from, and the local time behind any timestamp value
+- Filter devices by name, topic, model or manufacturer, and hide anything not in HomeKit
+- Toggle offered as an action wherever a device understands one
+
+### Changed
+
+- Rules never run on retained messages, so reconnecting cannot replay an old press
+- Per rule rate limit, a settling window for mirrors, and a rule that runs away is turned off and logged
+- Accessory names are corrected to what HomeKit accepts, rather than warned about on every start
+- Values that have not moved are no longer sent to HomeKit
+- State is copied at startup, and what was loaded is reported in the log
+
+### Fixed
+
+- The interface is sent the words a device uses for on and off, instead of assuming ON and OFF
+- Endpoints are named in rule dropdowns, so a device's channels can be told apart
+- A characteristic with no value yet reports the last known one rather than failing the read
+
+## [0.4.1] - 2026-08-18
+
+### Changed
+
+- Marked private, since the package is not published. `npm publish` now refuses rather than putting it on the registry by accident
+- Installation documents the only route that works, installing from source, rather than leading with an npm package that does not exist
+
+## [0.4.0] - 2026-08-18
+
+First release. Everything below arrived across v0.1.0 to v0.4.0, none of which was published separately.
+
+### Added
+
+- Homebridge platform plugin connecting to one MQTT broker shared by every source
+- Pluggable source adapters producing one normalised device model, so the HomeKit mapping never sees a source format
+- Zigbee2MQTT source discovering devices and their functions from `bridge/devices`, updating live on joins, renames and removals
+- `json-topic` source for publishers that put flat JSON on a topic per device, with properties inferred from the keys seen and unrecognised keys kept rather than dropped
+- Sources can be marked rules only, for devices another plugin already publishes to HomeKit
+- Password protected web interface listing every device and function, with live values over server sent events
+- Tick a function to publish it to HomeKit, applied immediately with no Homebridge restart
+- Tile type per endpoint, optional separate accessory per endpoint, and name overrides
+- Rename devices whose source does not name them itself
+- Filter devices by name, topic, model or manufacturer, and hide anything not in HomeKit
+- HomeKit mapping for on/off, brightness, fan speed and swing, thermostat, temperature, humidity, battery and child lock
+- Buttons inferred from the actions a device publishes, one service per physical button, with per gesture selection
+- Property name to characteristic table, so a new kind of sensor needs no change to the mapper
+- Functions with no HomeKit equivalent stay listed and marked, ready for the rules engine
+- Persistent state under the Homebridge storage path, kept out of `config.json`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026, Luud Jacobs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# MQ77 Customizer 1.5.0
+
+**This Homebridge plugin has been 100% vibe coded using Claude Code.**
+
+A Homebridge plugin that exposes MQTT devices to HomeKit and links them together, configured from a web interface instead of a config form. Devices and their functions are discovered from the broker, so nothing has to be typed out by hand.
+
+## Requirements
+
+- Node.js 20.19, 22.12 or 24 and up
+- Homebridge 1.8 or up
+- An MQTT broker, for example Mosquitto
+- Zigbee2MQTT, for the Zigbee2MQTT source
+
+## Installation
+
+Install it the way you install any Homebridge plugin, from the Plugins screen of the Homebridge UI or from the command line:
+
+```
+hb-service add homebridge-mq77-customizer
+```
+
+## Settings
+
+Everything is set in the plugin's settings form in the Homebridge UI, and each field says what it is for. There are three things to fill in:
+
+- **MQTT Broker**, where your broker is and what it wants to be called
+- **Sources**, one per publisher on that broker. A Zigbee2MQTT source needs its base topic, `zigbee2mqtt` unless you changed it. With no sources at all, that is what is assumed
+- **Web Interface**, a port and a password. The interface can switch your devices, so it refuses to start without one
+
+Everything else, which devices reach HomeKit and what they do between them, is set in the web interface itself.
+
+### Sources
+
+Two kinds. **Zigbee2MQTT** needs nothing but its base topic: it describes its own devices, so they arrive complete. **Flat JSON topics** reads any publisher that puts flat JSON on a topic per device, working the functions out from the keys it sees. Those accumulate across messages, so a partial update carrying one key does not redefine the device.
+
+Recognised keys are `state`, `level`, `speed`, `swing`, `temperature`, `humidity` and `co2_levels`. Anything else still becomes a function, typed from its value, and stays available to the rules engine.
+
+**Rules only** keeps a source's devices out of HomeKit while leaving them usable as rule triggers and targets. Set it where another plugin already publishes those devices, so they can't appear twice.
+
+**Topic filter** narrows what a flat JSON source listens to, as an MQTT filter, `+` standing for one level and `#` for the rest. Everything under the base topic by default.
+
+**Command topic suffix** is what is added to a device's topic to write to it, usually `set`. Without one the source is read only.
+
+### Describing a device
+
+A flat JSON topic carries no schema, so a function is only known once it has turned up in a payload. A fan that reports nothing but `state` until somebody changes its speed has no speed to tick. Name the missing functions under **Described devices** and they are there from the moment the device first reports.
+
+A device is named by the part of its topic after the base topic: one publishing on `<base topic>/kitchen_fan` is written as `kitchen_fan`, though the whole topic is accepted too. Only the recognised keys above can be named, since a name on its own says nothing about the kind of value it carries. A function the device does report is left exactly as reported.
+
+What was described is logged at startup, so a topic that matches no device is visible rather than silent.
+
+## Usage
+
+Open `http://<your-homebridge-host>:8888`, or whichever port you set, and sign in with the password from the settings.
+
+Keep it on your own network. Anybody who gets past that one password can switch every device the plugin publishes, so the port does not belong on the open internet or behind a port forward. Reach it from outside through a VPN, the way you would reach Homebridge itself.
+
+Every device found on the broker is listed with all of its functions, grouped into functions, settings and diagnostics and listed by name within each. Tick a function to publish it to HomeKit. Changes take effect immediately, with no Homebridge restart.
+
+Per device you can also:
+
+- choose the HomeKit tile: Switch, Outlet, Lightbulb or Fan
+- publish each endpoint as its own accessory, for multi channel switches
+- give it a name, a room and a kind, which this interface uses to label and group it
+
+Functions with no HomeKit equivalent are still listed and marked, and stay available to the rules engine rather than being hidden.
+
+Accessory names are corrected to what HomeKit accepts, which must start and end with a letter or number. A name in brackets, `Hall light (front door)`, is published as `Hall light front door`. The name shown here is left as you wrote it.
+
+### What reaches HomeKit
+
+| Function | Becomes |
+| --- | --- |
+| on/off | Switch, Outlet, Lightbulb or Fan, your choice |
+| brightness | Brightness on a Lightbulb |
+| temperature, humidity | their sensor services |
+| battery | a battery reading on the accessory, with a low warning |
+| child lock | the physical controls lock on the tile |
+| climate | a Thermostat, using the temperature range the device declares |
+| speed, swing | a Fan with rotation speed and swing |
+| button actions | one button per physical button, mapped to single, double and long press |
+
+Button names and gestures are worked out from the action names the device publishes, so a double rocker becomes three buttons without anything being typed out. Gestures HomeKit has no equivalent for, such as triple press, stay available to the rules engine.
+
+### Naming and grouping
+
+Every device takes a name, a room and a kind, set in its panel. They are for this interface: HomeKit keeps rooms in the Home app, where no accessory can set or read them.
+
+Marking a device as a Controller puts its button presses in the Activity tab, with their own filter. Only marked devices: every remote in the house reporting in would bury the rules.
+
+The name reaches HomeKit only where the source names nothing itself, which is the flat JSON publishers. Zigbee2MQTT owns its own names, so one set here stays in this interface. Renaming never changes an accessory's identity, so nothing is lost in the Home app either way.
+
+### Last seen and retainment
+
+A device card says when the device was last heard, and its panel says the timestamp behind that along with whether the broker keeps its messages.
+
+Both come from the source rather than from this plugin. When a message reached the broker is not an answer to when a device spoke: a retained message is replayed the moment the plugin connects, which would have every retaining device looking as though it had just reported. Zigbee2MQTT publishes the real answer once `advanced.last_seen` is set to something other than `disable`, and a flat JSON publisher that puts a `last_seen` in its payload is taken at its word the same way. A device that publishes no such time shows none, and sorting by Last seen puts those last.
+
+Whether messages are retained is read from Zigbee2MQTT's own configuration, where three things decide it: the device's own `retain`, the `device_options` defaults it otherwise inherits, and `mqtt.force_disable_retain`, which overrides both. A source that keeps no such configuration says nothing rather than guessing.
+
+### Controllers
+
+The Controllers tab lists every device marked as a Controller, one table per remote, saying what each of its buttons sets off. A button no rule answers reads as `none`, or `In HomeKit` where the press reaches HomeKit as well, said under any rules it does answer. The Unused buttons and HomeKit buttons ticks in the header say which of those lines are wanted, and a button neither tick keeps is left out. Download writes the whole overview to `controller-config.md`, which follows the tick: hidden buttons are left out of the file too.
+
+### Map
+
+The Map tab draws the Zigbee network: what reaches the hub directly and what reaches it through something else. Every link found is drawn, and the route each device uses back to the hub is picked out.
+
+A scan questions every device in turn, so it takes minutes on a mesh of any size and only runs when asked for. Zigbee2MQTT only: a flat JSON source has no network to describe.
+
+### Activity
+
+The Activity tab lists what the rules have been doing, newest first, including the ones that decided not to run and why. A press and the rule it set off read as one line, and each entry says which kind of rule it was. Presses that set nothing off have a filter of their own, off by default.
+
+## Rules
+
+Rules live in four tabs: Automation, Mirror devices, Sliders and Timers. Automation is the general one: when something happens on one device, send something to another. All four work across sources, so a Zigbee button can drive an infrared blaster, and apply the moment they are saved.
+
+Across all four:
+
+- anything readable can set a rule off, including functions that never reach HomeKit, and anything writable can be acted on
+- an action can copy whatever set the rule off, restated in the target's own terms, so a switch that says `ON` can drive one that expects `true` and a dimmer counting to 254 can drive one counting to 100
+- a rule with several outcomes runs the first whose condition holds and skips the rest
+- picking what sets a rule off marks any value another rule already uses with a `*`, since two rules on one button press is a mistake nobody sees until both of them run
+- rules never run on retained messages, so reconnecting to the broker cannot replay yesterday's button press
+- a rule will not run more often than its rate limit, one second by default, and one that runs more than twenty times in ten seconds is switched off and logged on the assumption it is setting itself off
+
+An automation or a timer can be run by hand with the Trigger button beside Save, whether or not it is switched on. Only what has been saved can be run.
+
+### Mirror devices
+
+Which devices, and which of their functions, should stay in step. Every member is both a trigger and a target. Functions are matched on meaning rather than on name, so a socket calling its on/off `state` mirrors a two channel switch calling the same thing `state_l1`.
+
+After a write the group is left to settle, one and a half seconds by default and set per rule between 0.25 and 60 seconds. A device reporting its old state once more is indistinguishable from somebody flipping a switch, so without the pause a group that disagrees would send itself back and forth for ever. The cost is that flipping a mirrored device again inside the window is ignored.
+
+### Timers
+
+A wait between one thing and another: a light coming on, thirty seconds, the light going out again.
+
+The clock starts again if the same thing happens again. It is called off the moment what started it stops being true: told to run when a light came on, it stops caring once the light is off, however that happened. A timer counting when Homebridge restarts is forgotten.
+
+An automation with a delayed action does the first half of this and cannot be called off, which is the difference between the two.
+
+### Sliders
+
+A dimmer driven from buttons. One press moves one step. Down from the first step switches the device off rather than leaving a light at zero brightness and still on, and either stepping button switches it on when it is off.
+
+Coming on from off lands where the device says it should, which Zigbee2MQTT keeps as `level_config.on_level`. "On at" sets it for a device that has no such setting, and without either it comes on at the first step.
+
+Cycle is one button for the whole range: up to the top, back down to off, and up again from there. It starts upward whenever the level was last set by something other than the slider, and ignores a second press within a second, since it is a button to press rather than to hold.
+
+Each button takes several triggers, so one slider can be driven by more than one remote. Stepping counts from what the slider last sent for a couple of seconds rather than from what the device last reported, so a held button that sends faster than the light can answer still climbs.
+
+## Backup settings
+
+Everything set here lives in `state.json` under the Homebridge storage path, alongside a `backups` folder holding the last ten dated copies. One is taken when the plugin starts, before anything is touched, and at most once an hour after that.
+
+The footer offers `back up: download / upload`, along with when the last copy was taken and a way to take one now. Download hands you the lot as a file, which is the only copy that survives losing the machine it runs on. Upload takes one back, after copying what it replaces. The session secret is left out of the download and kept on upload, so a settings file is safe to keep somewhere else and putting one back does not sign you out.
+
+A run that starts with nothing will not write over a file that has something in it. Somebody deleting their last rule is entitled to an empty file, but a run that began empty and is about to stamp on one that is not has misread something, and the file is worth more than the write. It says so in the log and in the interface rather than carrying on.
+
+## Links
+
+[License](https://github.com/LuudJacobs/homebridge-mq77-customizer/blob/main/LICENSE) • [Changelog](https://github.com/LuudJacobs/homebridge-mq77-customizer/blob/main/CHANGELOG.md)