homebridge-pax-calima 2.4.5 → 2.5.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+[Release notes](RELEASE_NOTES.md) describe the proposed update. Beta entries are consolidated into the stable release when it is promoted; beta history remains in GitHub prereleases and tags.
+
+## 2.5.0-beta.2 — Patient requests, truthful tiles
+
+- Keep Boost, Pause and speed requests pending through temporary Bluetooth failures, including child-bridge restarts. A newer manual command replaces the pending request.
+- Confirm the fan's state before showing an action as active. Check uncertain writes before retrying, preserving an already-running timer.
+- Restore measured speed after HomeKit caches a requested slider position.
+- Retry stalled disconnects and wait for scanning to stop before connecting.
+- Allow a short authentication processing interval before protected controls and log differing manual readback without exposing PINs.
+- Retain a recent verified reading during a missed background poll, within the existing 45-second freshness limit.
+- Add explicit Boost/Pause tile names and identify the fan in communication logs.
+- Add an optional speed-target limit for each fan, covering Boost and the Home speed slider. This accommodates the owner's older Wetroom fan, which accepts 2400 RPM and returns zero RPM for a 2450 RPM request, while retaining Kitchen's existing setting.
+- Stop retries for rejected authentication, invalid data, explicitly different control readback or unsupported operating modes. Siri can still time out before Bluetooth recovers; a pending request continues until confirmed, replaced or stopped by one of these faults.
+
+- Point the plugin website and support links to the new [SvaraHome site](https://homebridge.svarahome.kernowekconsulting.co.uk).
+- Confirm live Boost, Pause and cancellation on both fans, plus capped slider control on Wetroom. All 48 automated tests pass across Node 22/24 and Homebridge 1/2 for the control implementation.
+
+## 2.5.0-beta.1 — Boost and Pause
+
+### SvaraHome
+
+- Introduced the SvaraHome name across the plugin listing, setup guidance and release copy.
+- Added the approved layered house-and-fan logo and prepared a Homebridge icon.
+- Retained the existing package identifier and fan accessory identities for upgrade continuity.
+
+### Everyday controls
+
+- Added timed Boost and Pause switches, shown by default with individual visibility settings.
+- Added early return to automatic ventilation and readback after control commands.
+- Used the fan’s native timer so temporary actions can finish while Homebridge is disconnected.
+- Changed the speed slider to temporary manual control, preserving persistent speed presets.
+- Made Boost and Pause mutually exclusive and prevented an inactive switch-off from cancelling the other action.
+- Restricted manual controls to operating mode 00 without changing installation settings.
+
+### Bluetooth and telemetry
+
+- Added explicit address/PIN routing and validation for six- and eight-digit PINs.
+- Required confirmed authentication and stopped unattended retries after a rejected PIN.
+- Queued Bluetooth sessions across fans and added bounded operations, connection cleanup and late-connection recovery handling.
+- Reported communication failures for unconfirmed commands, stale telemetry and invalid readings.
+- Reconciled the fan’s current override through polling and after restart.
+
+### Setup and upgrades
+
+- Replaced the non-actionable Boost event service.
+- Removed unsupported temperature, humidity and light services.
+- Applied changed quiet-hours schedules once, preserving later official-app edits.
+- Updated configuration guidance and supported Node versions.
+- Added 32 automated tests covering protocol handling, native Homebridge services, configuration, queues, recorded telemetry and the maintained Bluetooth library’s real classes.
+
+### Dependency security
+
+- Replaced the old Bluetooth dependency with the maintained Noble fork, removing the vulnerable archive and native-build dependency chain.
+- Confirmed zero reported vulnerabilities in fresh full and production audits, including a separately resolved Linux ARM64 production tree.
+- Added high/critical audit gates and a native-module load check to CI.
+
+### Beta validation
+
+- Automated tests passed across Node 22/24 and Homebridge 1/2.
+- Verified isolated native Linux ARM64 installation/loading on the Pi under Node 22/24, without initialising Bluetooth or changing the running bridge.
+- Live plugin deployment and older-fan authentication remain outstanding.
+- Homebridge verification remains pending.
+
+## 2.4.5
+
+- Replaced the removed Silent Hours service lookup with `getServiceById` for Homebridge 2 compatibility.
+- Reported live validation on Homebridge 2.4.0 and Node 24.19.0.
+
+## 2.4.4
+
+- Improved Silent Hours time-field hints and invalid-time warnings.
+
+## 2.4.3
+
+- Added schedule configuration, an optional Silent Hours switch and optional light sensor exposure.
+- Added plugin display metadata and reorganised settings.
+- Wrote Silent Hours during every poll. This behaviour is replaced in 2.5.0.
+
+## 2.4.2
+
+- Disabled the optional humidity tile by default and rewrote setup guidance.
+
+## 2.4.1 / 2.4.0
+
+- Revised Bluetooth connection handling and polling.
+
+## Earlier releases
+
+- Added initial Bluetooth integration, Homebridge lifecycle changes and fan services. Earlier sensor interpretations are corrected in 2.5.0.

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -1,228 +1,81 @@
-# homebridge-pax-calima
+# SvaraHome for Homebridge
 
-**Bring your bathroom fan into Apple Home — no hub, no cloud, just Bluetooth.**
+Give the fan a boost. Pause it for a quiet moment. Let it return to normal when the time is up.
 
-If you have a **Pax Calima** or **Vent-Axia Lo-Carbon Svara** extractor fan, this plugin connects it directly to HomeKit via Bluetooth. Once set up, your fan appears in the Home app with live temperature and fan speed — and you can build automations around all of them.
+SvaraHome brings local Bluetooth control for Pax Calima and Vent-Axia Svara fans in Apple Home. No cloud account is needed.
 
-[![Homebridge 2 Ready](https://img.shields.io/badge/Homebridge-2%20Ready-brightgreen)](https://github.com/homebridge/homebridge/wiki/Updating-To-Homebridge-v2.0)
-[![npm](https://img.shields.io/npm/v/homebridge-pax-calima)](https://www.npmjs.com/package/homebridge-pax-calima)
+[Visit SvaraHome for setup guidance and support](https://homebridge.svarahome.kernowekconsulting.co.uk).
 
----
+## Set up your fan
 
-## Is this the right plugin for your fan?
+Install `homebridge-pax-calima` through Homebridge UI, then open Plugin Config. Add each fan's Bluetooth address and its own six- or eight-digit PIN from the official app. Keep leading zeroes. Close the official app while Homebridge connects.
 
-This plugin works with fans that connect via the official **Pax** or **Vent-Axia** Bluetooth app. If your fan has a MAC address starting with `58:2b:db`, you're in the right place.
-
-**Confirmed compatible:**
-- Pax Calima — Sweden, Norway, Denmark, Finland, Spain, Portugal
-- Vent-Axia Lo-Carbon Svara White — UK
-- Vent-Axia Lo-Carbon Svara Black — UK
-
-These fans are hardware-identical. The same plugin works for all of them.
-
----
-
-## What you get in the Home app
-
-Each fan appears as a single accessory with:
-
-- 💨 **Fan speed** — shows current RPM as a percentage, live and accurate
-- 🌡️ **Temperature** — live reading, updates every ~20 seconds
-- ⚡ **Boost** — a button that triggers the fan's high-speed boost mode
-- 🌙 **Silent Hours** — keeps the fan quiet at night; set a schedule, a switch, or both (see below)
-- 💧 **Humidity** — available but off by default (read below before enabling)
-- 💡 **Light level** — available but off by default (read below before enabling)
-
-> Accessories appear in the **Home app on your iPhone**, not the Homebridge UI accessories tab — that's normal for child bridge plugins.
-
----
-
-## Before you start
-
-You'll need:
-- Homebridge `^1.6.0` or `^2.0.0`
-- Node.js `18.20.4` or later
-- A Bluetooth adapter on your Homebridge host (the Pi 4's built-in adapter works well)
-
-**Running Homebridge OS on a Raspberry Pi?** There's one extra step after installation. Run this once in the **Homebridge terminal**:
-
-```bash
-sudo setcap cap_net_raw+eip /opt/homebridge/bin/node
-```
-
-If Bluetooth shows as off after that:
-
-```bash
-sudo rfkill unblock bluetooth
-```
-
-If things still aren't working after both of those — unplug the Pi, wait 10 seconds, plug it back in. A full power cycle rather than a software restart is sometimes needed to reinitialise the Bluetooth stack cleanly.
-
----
-
-## Installation
-
-Search for **Pax Calima** or **Svara** in the Homebridge UI and click Install.
-
-Or via terminal:
-```bash
-npm install -g homebridge-pax-calima
-```
-
----
-
-## Configuration
-
-**You don't need to configure anything to get started.** The plugin finds your fan automatically and registers it in HomeKit.
-
-A full config example with all options:
+Use Node 22.12 or later within Node 22, or Node 24, with Homebridge 1.8+ or 2. A working Bluetooth adapter and the normal Bluetooth access for your Homebridge installation are required. A dedicated child bridge is recommended. This plugin does not alter system permissions or install system tools.
 
 ```json
 {
   "platform": "PaxCalima",
-  "name": "Pax Calima / Vent-Axia Svara",
-  "silentHoursStart": "23:00",
-  "silentHoursEnd": "07:00",
-  "showSilentSwitch": false,
-  "showHumidity": false,
-  "showLight": false,
+  "name": "SvaraHome",
   "fans": [
-    {
-      "name": "Wetroom Fan",
-      "mac": "58:2b:db:xx:xx:xx",
-      "pin": "012345"
-    }
-  ]
+    { "name": "Kitchen Fan", "mac": "58:2b:db:12:34:56", "pin": "00123456" }
+  ],
+  "boostMinutes": 10,
+  "boostRpm": 2000,
+  "pauseMinutes": 10
 }
 ```
 
-| Setting | Default | What it does |
-|---|---|---|
-| `silentHoursStart` | — | Time the fan stops boosting at night, e.g. `"23:00"` |
-| `silentHoursEnd` | — | Time the fan resumes boosting, e.g. `"07:00"` |
-| `showSilentSwitch` | `false` | Adds a Silent Hours switch to the Home app — great for Goodnight scenes |
-| `showHumidity` | `false` | Shows humidity tile — read the note below first |
-| `showLight` | `false` | Shows light tile — read the note below first |
-| `fans[].name` | Auto | Friendly name for a specific fan |
-| `fans[].mac` | — | Only needed to assign a custom name or PIN |
-| `fans[].pin` | `012345` | 6-digit PIN — only change if set via the official app |
-
----
-
-## Silent Hours
-
-Silent Hours tells the fan not to boost during a set period — useful for not being woken by a noisy fan at 3am.
-
-**Two ways to use it — pick one or combine both:**
-
-**Schedule (set and forget):** Set `silentHoursStart` and `silentHoursEnd` in your config using 24-hour format. The plugin calculates whether you're in the quiet window on every poll and writes the schedule to the fan automatically. Overnight spans work correctly — `23:00` to `07:00` does what you'd expect.
-
-**Switch (for scenes and shift workers):** Set `showSilentSwitch: true` to add a Silent Hours on/off switch to your accessory. This is ideal for including in a **Goodnight scene** alongside lights and heating — one tap and the fan goes quiet with everything else. It's also the right choice if your sleep schedule changes regularly, like shift work, where a fixed time window doesn't suit.
-
-**Using both together:** If you set a schedule AND enable the switch, the switch takes priority when you toggle it manually. The schedule still runs in the background — useful as a safety net if you forget to turn the switch back on.
-
----
-
-## A note on humidity and light
-
-Both tiles are **off by default**, and for good reason.
-
-During testing we confirmed that both sensors — while active on the device — don't expose live readings via Bluetooth. The fan uses them internally to decide when to boost, but the BLE characteristic returns the fan's last internal threshold state rather than a continuous measurement. In practical terms:
-
-- With all lights off at 21:20, the fan's Bluetooth still reported **52 lux**
-- After a shower that raised the room to **89% humidity**, the Bluetooth still reported **50%**
-
-This isn't a bug in the plugin — it's how the fan's firmware works (confirmed on firmware 02.08, and consistent with observations from the Home Assistant community).
-
-**If you turn them on**, be aware that:
-- Asking Siri "what's the humidity in the bathroom?" will likely return a stale number
-- Automations based on these values won't fire reliably
-
-**What does work well for shower detection:** when the fan's internal humidity sensor detects a sharp rise, it boosts to near full speed automatically. A `Fan Speed > 75%` automation in Apple Home is a reliable, practical trigger for "shower in use."
-
-If you want to enable humidity or light anyway — perhaps for settled ambient readings — set `showHumidity: true` or `showLight: true` in your config.
-
----
-
-## Fan speed control — it depends on how your fan is wired
-
-The fan can be installed in two wiring modes:
+The address and PIN above are examples. Each fan needs its own entry. An empty or invalid configuration does not start Bluetooth discovery. Incorrect fan entries are skipped, with a short explanation in the Homebridge log. There is no fallback PIN or automatic pairing with nearby fans.
 
-**Intermittent mode** — the fan is off by default and spins up when triggered. In this mode the speed slider in Apple Home works as expected.
+## In Apple Home
 
-**Always-on (trickle) mode** — the fan runs continuously at a speed managed by its own controller. Speed commands are accepted via Bluetooth but the fan resets to its own setpoint within seconds. The slider shows the current speed accurately but can't override it.
+**Boost** runs the fan at your chosen speed for the configured time. Turn it off to return to automatic ventilation. Turn it on again to start a fresh full duration.
 
-Not sure which mode you have? If your fan is always running — even quietly — you're in always-on mode. In either mode, temperature, fan speed and automations work perfectly.
+**Pause** stops the fan temporarily. The fan's own timer returns it to automatic ventilation, even if Homebridge disconnects. Turn Pause off to resume sooner. The motor can take several seconds to respond.
 
----
+Boost and Pause share one manual override: starting one replaces the other. Switching off an already inactive control leaves the other action alone. The switches follow the fan's readback, including actions started in the official app; updates arrive after a successful poll, normally around every ten seconds plus Bluetooth connection time. Home does not show a remaining-time countdown.
 
-## Something not working?
+Name the switches clearly in Home, such as Kitchen Boost and Kitchen Pause. You can then use scenes or Siri phrases such as “Turn on Kitchen Boost” and “Turn on Kitchen Pause”. Siri wording and tile grouping depend on your Home setup; a custom scene can provide your preferred phrase.
 
-**Fan not showing up in Home**
-Run `hciconfig` in the Homebridge terminal — you should see `UP RUNNING`. If it shows `RF-KILL`, run `sudo rfkill unblock bluetooth`. If still nothing, unplug the Pi and power cycle it.
+The fan's speed slider starts a temporary manual session using the Boost duration. Nonzero targets range from 1000 to 2500 RPM in steps of 25; percentages below 40% request the minimum 1000 RPM. Zero starts Pause. The displayed percentage follows measured RPM, so it can differ while the motor settles. Turning the fan off starts a timed Pause; turning it on clears an active Pause and returns to automatic ventilation. Automatic mode may still leave the motor idle under its native rules.
 
-**setcap not taking effect**
-Make sure you're targeting the right binary — on Homebridge OS it's `/opt/homebridge/bin/node`, not the system Node.
+Each fan can have its own **Maximum requested speed** in Plugin Config (`maxManualRpm`). This caps both Boost and speed-slider targets for that fan while keeping the displayed speed tied to measurement. Leave it blank for the normal 2500 RPM target limit. The owner's older Wetroom fan accepted 2400 RPM but returned zero RPM for a 2450 RPM request; its validated limit is therefore set to 2400. This observation does not establish the limit for every fan with that firmware.
 
-**Wrong PIN**
-Default is `012345`. If you changed it in the official app, add the fan to the `fans` config array with the correct PIN.
+After saving configuration changes, use **Restart Child Bridge** on SvaraHome's plugin card. During validation, terminating the child process directly reloaded its source but retained the parent's previous configuration; the Homebridge UI restart applied the saved fan limit.
 
-**Speed slider does nothing**
-Your fan is in always-on mode — see above. Everything else works normally.
+Hide either switch in Plugin Config if you prefer fewer tiles. Hiding a switch does not cancel a running action. Temporary controls currently require operating mode 00, the mode tested on the newer Kitchen fan. The plugin refuses controls in other modes and does not change installation modes.
 
-**Humidity or light reading seems stuck**
-This is expected firmware behaviour — see the sensor note above.
+## Quiet hours
 
-**Accessories not appearing in Home**
-Go to Homebridge UI → plugin settings → Remove Accessory Cache, then restart. They'll reappear within a few seconds.
+Leave both time fields blank to retain the fan's own schedule. To save a new schedule, enter different start and end times in 24-hour format. A changed plugin schedule is applied and checked once. Later changes in the official app are retained across polls and Homebridge restarts.
 
----
+The optional Silent Hours switch enables or disables that saved schedule while preserving its times. It does not start an immediate quiet period; use Pause for that. Native quiet-hours suppression of automatic boosts has not yet been behaviorally verified by this project.
 
-## Homebridge 2 compatibility
+## Upgrading from 2.4.x
 
-This plugin is compatible with Homebridge 2:
-- Registered as a dynamic platform
-- Waits for `didFinishLaunching` before starting BLE or accessory work
-- Uses the Homebridge 2-compatible `Accessory.getServiceById()` API for the optional Silent Hours service
-- No analytics, tracking or post-install scripts
-- Accessories restore cleanly from cache without re-registration
-- Requires Node.js 18.20.4 or later
-- Live-tested on Homebridge 2.4.0 (HAP 2.2.2) with Node.js 24.19.0
+- Retain the existing fan accessory and its Home assignment. Correct each fan's address/PIN in Plugin Config; name-only entries cannot be routed safely.
+- The old event-only Boost button is replaced by an actionable switch. Check scenes that referred to the old service. Pause is added by default.
+- Temperature, humidity and light tiles are removed. The previous humidity/light values came from a heat-setting characteristic; the previous temperature conversion remains unverified. These values should not drive automations. Old `showHumidity` and `showLight` settings are ignored.
+- Speed control now uses temporary manual override, leaving humidity, light and trickle speed presets alone.
+- Quiet hours are no longer rewritten on every poll. The switch represents the native schedule's enabled flag.
+- No factory reset or accessory-cache reset is required.
 
----
+## When a fan is unavailable
 
-## Release notes
+Boost, Pause and speed requests remain pending through temporary Bluetooth failures. SvaraHome retries every ten seconds after a failed attempt until readback confirms the request or a newer manual command replaces it. Pending requests survive child-bridge restarts. To cancel a pending Boost, turn Boost off; to cancel a pending Pause, turn Pause off. A request may therefore run when the fan becomes reachable later.
 
-### 2.4.5
-- **Fixed:** Homebridge 2 compatibility for the optional Silent Hours switch. Homebridge 2 removed `Accessory.getServiceByUUIDAndSubType()`; both lookups now use the supported `Accessory.getServiceById()` API.
-- **Verified:** Live-tested successfully on Homebridge 2.4.0 (HAP 2.2.2) with Node.js 24.19.0 on Homebridge OS.
-- No BLE protocol, fan control, sensor mapping, configuration, or accessory behaviour changes.
+The tiles follow verified fan state, never the pending request. If a reply is lost after a write, a retry first checks whether the requested override is already running, avoiding repeated timer extensions. Siri or HomeKit can time out before recovery; an error from Siri does not cancel the pending request or prove the fan did not receive it. Homebridge logs identify pending requests.
 
-### 2.4.4
-- **Fixed:** Silent Hours time fields no longer show a raw regex pattern as validation hint in the Homebridge UI — replaced with plain human-readable placeholder text (e.g. `23:00`) and a description
-- **Improved:** Invalid time format now logs a clear warning message rather than silently disabling the schedule
+A missed background poll retains the last verified reading only within the existing 45-second freshness limit. Home reports a communication failure when authentication fails, a command fails, telemetry is stale or RPM is outside the accepted range. Rejected authentication, invalid data, an explicitly different control readback and unsupported operating modes stop command retries and need attention. A rejected PIN also stops unattended authentication retries; correct the configuration and restart the child bridge, then issue the request again.
 
-### 2.4.3
-- **Silent Hours** reworked — now supports a config schedule (`silentHoursStart` / `silentHoursEnd`) that runs automatically, an optional HomeKit switch (`showSilentSwitch: true`) for Goodnight scenes and irregular schedules, or both together. The switch takes priority when toggled manually; the schedule runs as a background default. Any existing Silent Hours switch from earlier versions is automatically removed unless `showSilentSwitch` is enabled.
-- **Light sensor** (`showLight`) added as opt-in — confirmed via live testing that the characteristic returns a static value regardless of lighting conditions.
-- **`showSilentSwitch`**, **`showHumidity`** and **`showLight`** grouped under "Optional Sensors" in the Homebridge UI config for a cleaner settings experience.
-- **`displayName`** added to `package.json` — shows correctly as "Vent-Axia Svara / Pax Calima" in the Homebridge UI.
-- Sensor characteristic only read when at least one optional sensor is enabled — slightly leaner poll cycle for most users.
-- Silent Hours written to fan on every poll — stays in sync after power cuts.
+Check the fan's address and PIN securely in Plugin Config, Bluetooth range and adapter access, and whether another app is connected. The plugin never prints PINs or raw backend errors. After a timed-out disconnect, it retries disconnection before allowing another session to use the radio. It waits for scanning to stop before connecting. Persistent adapter failures may still require attention.
 
-### 2.4.2
-- Humidity sensor disabled by default — opt-in via `showHumidity: true`
-- README rewritten with a more human tone
+## What has been checked
 
-### 2.4.1
-- Fixed sensors returning stale values — reverted to connect→read→disconnect per poll
+Device-level trials on the owner's newer eight-digit-PIN Kitchen fan established timed Boost, timed zero-RPM Pause, expiry, early resume and speed changes. All tested settings were restored. Both Kitchen and the older Wetroom fan subsequently authenticated and provided telemetry after Wetroom's address and PIN were corrected. Kitchen's pending-command retries were also exercised through HomeKit switches. Wetroom's firmware 02.08 accepted a temporary 2400 RPM Boost, confirmed by HomeKit readback, and returned to automatic ventilation after cancellation. Its initial 2450 RPM request produced a zero-RPM override; the per-fan target limit addresses this observed difference.
 
-### 2.4.0
-- Rebuilt with persistent connection architecture
+Version 2.5.0-beta.2 adds recovery and pending-command fixes to beta.1. The control implementation has been tested on the owner's Pi, with automated protocol, queue and native Homebridge-service checks. See [live diagnostic evidence](docs/BETA1-LIVE-DIAGNOSTIC.md), [validation](docs/VALIDATION.md), [release notes](RELEASE_NOTES.md) and [changelog](CHANGELOG.md). Brief successful sessions do not establish sustained Bluetooth reliability.
 
-### 2.3.x / 2.2.1 / 2.1.0
-- Correct sensor UUIDs and byte mappings confirmed via live device testing
-- Homebridge 2.0 initialisation fixes; duplicate accessory registration resolved
+Homebridge verification remains an aim. The SvaraHome logo is bundled for the icon request; Homebridge controls verified status and icon display. See [verification preparation](docs/VERIFICATION.md).
 
-### 1.0.x
-- Initial releases
+Dependency security: this candidate uses the maintained Noble library. The recorded six high and one critical dependency findings have been removed; fresh audits report zero vulnerabilities. See [security evidence](docs/DEPENDENCY-SECURITY.md).

package/RELEASE_NOTES.md

@@ -0,0 +1,41 @@
+# SvaraHome 2.5.0-beta.2 — Patient requests, truthful tiles
+
+Ask for a boost. Let SvaraHome work through a temporary Bluetooth interruption. See what the fan has confirmed.
+
+This beta builds on SvaraHome's timed Boost and Pause controls, with recovery improvements tested on both the newer Kitchen fan and the older Wetroom fan.
+
+## A request worth waiting for
+
+Boost, Pause and speed requests now stay pending through temporary Bluetooth failures. SvaraHome retries after a failed attempt, including after a child-bridge restart. A newer manual command replaces the waiting request.
+
+For example, say, “Siri, boost the kitchen fan.” Siri may still time out while Bluetooth recovers; the request can continue afterwards. Turn Boost off to cancel a pending Boost, or Pause off to cancel a pending Pause. A waiting request can start when the fan becomes reachable later.
+
+Rejected authentication, invalid data, unsupported operating modes and an explicitly different control readback stop retries and need attention.
+
+## What Home shows
+
+Boost and Pause follow the fan's confirmed manual state. The speed slider returns to measured speed after a request, rather than staying at the percentage you asked for.
+
+An uncertain write is checked before it is repeated, so an already-running timer is preserved. A missed background poll retains the last verified reading only within the existing 45-second freshness limit. Failed commands and stale or invalid readings report a communication fault.
+
+Bluetooth recovery now retries stalled disconnects and waits for scanning to stop before connecting. Logs identify which fan needs attention, and Boost and Pause have explicit tile names.
+
+## A limit for each fan
+
+The optional **Maximum requested speed** setting caps Boost and slider targets separately for each fan. Measured speed remains unchanged.
+
+Our older Wetroom fan accepted 2400 RPM but returned a zero-RPM override for a 2450 RPM request. Its tested limit is now 2400 RPM; Kitchen retains 2450 RPM. This is evidence from these fans, rather than a universal limit for every firmware version.
+
+## Before you upgrade
+
+Check that each fan has its own Bluetooth address and correct six- or eight-digit PIN. Close the official app while Homebridge connects. After saving configuration changes, use **Restart Child Bridge** on SvaraHome's plugin card so the saved settings are loaded.
+
+Timed controls keep the fan's own expiry timer and leave persistent ventilation presets in place. Existing fan identities and room assignments are retained. If upgrading from 2.4.x, check scenes that used the old Boost event button; it is replaced by a working switch. Unsupported temperature, humidity and light tiles are removed.
+
+Setup guidance and support now live at the [SvaraHome website](https://homebridge.svarahome.kernowekconsulting.co.uk).
+
+## Tested, with more to learn
+
+Live checks confirmed Boost, Pause and cancellation on both fans, plus the capped speed slider on Wetroom. The control implementation passed 48 automated tests in each Node 22/24 and Homebridge 1/2 combination. Short successful trials do not establish uninterrupted Bluetooth reliability, and Siri voice recognition still depends on your Home names and scenes.
+
+This is a testing release. Homebridge verification remains pending.

package/assets/README.md

@@ -0,0 +1,13 @@
+# SvaraHome artwork
+
+SvaraHome belongs to the same visual family as GivHome: a rounded-square tile and layered house, with a turquoise three-bladed fan replacing the GivHome letter.
+
+Brand blue: `#026AB3`. The house uses layered cool blues, clear roof eaves and restrained highlights. The fan remains legible within a white circular face. The app/plugin icon carries no text so it reads at small sizes.
+
+- `svarahome-master.png`: selected full-size generated artwork.
+- `svarahome.png`: 1024 × 1024 project icon.
+- `homebridge-pax-calima.png`: 100 × 100 PNG for the existing npm package’s Homebridge icon request.
+
+The original supplied GivHome image and the two SvaraHome drafts remain untouched in the owner’s files. This icon was produced with the built-in image generation tool; the final prompt is saved in `docs/BRANDING.md`.
+
+Homebridge maintains plugin icons centrally. Submit the small icon with verification, or request its registration after verification. The artwork does not imply manufacturer endorsement or Homebridge verification.