homebridge-pax-calima 2.5.0 → 2.5.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.5.2
+
+- Now verified by Homebridge.
+
+## 2.5.1
+
+- Set a conservative 2400 RPM default limit for temporary Boost and speed-slider requests, avoiding a rejected high-speed command that can put some fans into Pause. Explicit per-fan limits remain available.
+
 ## 2.5.0
 
 - Introduced **SvaraHome**, with a new name and house-and-fan identity.

package/README.md

@@ -1,5 +1,7 @@
 # SvaraHome for Homebridge
 
+[![Verified by Homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=flat)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+
 <img src="assets/svarahome.png" alt="SvaraHome’s blue house and fan logo" width="160">
 
 Give the fan a boost. Pause it for a quiet moment. Let it return to normal when the time is up.
@@ -8,7 +10,7 @@ SvaraHome brings local Bluetooth control for Pax Calima and Vent-Axia Svara fans
 
 [Website and support](https://homebridge.svarahome.kernowekconsulting.co.uk) · [Plugin on npm](https://www.npmjs.com/package/homebridge-pax-calima) · [Release notes](RELEASE_NOTES.md)
 
-**SvaraHome 2.5.0** brings timed Boost, Pause and confirmed fan feedback to Apple Home.
+**SvaraHome 2.5** brings timed Boost, Pause and confirmed fan feedback to Apple Home.
 
 ## What you get in Apple Home
 
@@ -84,7 +86,7 @@ The address and PIN are examples. Use your own fan’s details. A Bluetooth addr
 | `pauseMinutes` | Timed pause duration, including when the main Fan is turned off. Default: 10 minutes. |
 | `showBoostSwitch` | Show Boost Fan. Default: `true`. |
 | `showPauseSwitch` | Show the separate Pause Fan switch. Default: `false`; an explicitly enabled setting stays enabled. |
-| `fans[].maxManualRpm` | Optional per-fan limit for Boost and slider requests. Leave blank for the 2500 RPM target limit, or use a lower speed confirmed to work on your fan. This does not cap displayed measurement or alter permanent presets. |
+| `fans[].maxManualRpm` | Optional per-fan limit for Boost and slider requests. Leave blank for a conservative 2400 RPM target limit. Only raise it to a speed verified to work on your fan. This does not cap displayed measurement or alter permanent presets. |
 | `silentHoursStart` / `silentHoursEnd` | Optional saved quiet-hours schedule, in 24-hour format. Set both times, or leave both blank to retain the fan’s own schedule. |
 | `showSilentSwitch` | Show the saved schedule’s enable/disable switch. Default: `false`. |
 
@@ -100,8 +102,14 @@ Check its address and PIN privately in Plugin Config, Bluetooth range/adapter ac
 
 Temporary connection failures leave the newest manual request waiting for retry. A waiting request can start later when the fan reconnects. Turn the main Fan on to replace it with return-to-automatic. Siri may time out before recovery; that timeout does not cancel the waiting request.
 
+This also covers Pause On, Pause Off and returning to automatic ventilation. SvaraHome waits ten seconds after a failed attempt before retrying; requests share one Bluetooth queue, so delivery can take longer. Pending requests survive a child-bridge restart, and a newer manual command replaces the older request. A lost reply is checked against the running timer before resending, so recovery does not keep restarting the timer. Rejected credentials, invalid commands and mismatched fan readbacks stop retries and need correction.
+
 Tiles follow confirmed fan state. Background readings are retained only within a 45-second freshness limit; failed commands, stale data and invalid readings report communication faults. A rejected PIN stops unattended authentication retries: correct the saved details, restart the child bridge, then try again.
 
+If Boost fails with `COMMAND_NOT_CONFIRMED`, check the requested and received values in the log. Some fans return a timed Pause when they reject a high RPM target. Set that fan’s **Maximum Manual RPM** to a speed verified to work, then restart its child bridge. Clear any resulting Pause to return to automatic ventilation. A mismatched readback stops the request rather than repeatedly sending the rejected target.
+
+For sensor automations, select **Boost Fan → Turn On**. The main **Fan → On** returns to automatic ventilation. Home’s **Test This Automation** lets you check the saved action separately from a new sensor event.
+
 ## Upgrading to 2.5
 
 Keep the existing fan accessory and its room assignment. Check each fan’s address/PIN and any scenes that used the previous Boost event service. Boost is now an actionable **Boost Fan** switch; **Pause Fan** is optional. Unsupported temperature, humidity and light services are removed, and the speed slider now controls a temporary session.

package/RELEASE_NOTES.md

@@ -1,33 +1,3 @@
-# SvaraHome 2.5.0 — Your fan, at home
+# SvaraHome 2.5.2
 
-A boost when you need it. A quiet moment when you want one. An easy way back to normal.
-
-Meet **SvaraHome**: a new name, a new look and more useful everyday control of your Pax Calima or Vent-Axia Svara fan in Apple Home.
-
-## Familiar controls
-
-**Fan** is your everyday control. Turn it off for a timed pause; turn it on to return to automatic ventilation, whether the fan was paused or boosted.
-
-**Boost Fan** gives ventilation a temporary lift at your chosen speed and duration. The fan’s own timer returns it to automatic operation, even if Homebridge disconnects. Turn Boost Fan off to return sooner.
-
-Try “Siri, turn on Boost Fan in the kitchen”, using the names and rooms in your Home. A separate **Pause Fan** switch is optional for status and automations.
-
-The speed slider now starts a temporary session, leaving your saved ventilation speed presets in place. Each fan can have its own requested-speed limit.
-
-## Clearer feedback, less maintenance
-
-Controls reflect the fan’s confirmed state and measured speed. Failed commands or stale readings show a communication fault, so an unconfirmed request is not presented as success.
-
-Temporary Bluetooth interruptions no longer mean repeating your request: SvaraHome retries and keeps your latest instruction, including across child-bridge restarts. Siri may time out before recovery; a waiting request can still run when the fan reconnects.
-
-Quiet-hours schedules are saved when you change their times. Later schedule changes in the official app are respected.
-
-## Before you upgrade
-
-- Give every fan its own Bluetooth address and correct six- or eight-digit PIN in Plugin Config. Close the official app while Homebridge connects.
-- Boost and Pause use the durations in SvaraHome’s Plugin Config, both 10 minutes by default. They do not inherit the countdown selected in the official app. Fan Off is temporary: automatic ventilation resumes when the Pause timer ends.
-- Existing fan identities and room assignments are retained. Check scenes that used the old Boost event service, which is replaced by the working Boost Fan switch.
-- Temperature, humidity and light tiles are removed because they were not verified ambient measurements.
-- Use Node 22.12 or later within Node 22, or Node 24, with Homebridge 1.8+ or 2. After saving configuration, use Restart Child Bridge on SvaraHome’s plugin card.
-
-Setup guidance and support are at the [SvaraHome website](https://homebridge.svarahome.kernowekconsulting.co.uk).
+Now verified by Homebridge.

package/config.schema.json

@@ -41,8 +41,8 @@
               "minimum": 1000,
               "maximum": 2500,
               "multipleOf": 25,
-              "placeholder": "2500",
-              "description": "Optional. Limits Boost and speed-slider requests for this fan. Leave blank for 2500 RPM. Some older fans reject higher requests; use a speed confirmed to work on your fan. This does not change its permanent presets."
+              "placeholder": "2400",
+              "description": "Optional. Limits Boost and speed-slider requests for this fan. Leave blank for a conservative 2400 RPM limit. Some fans return Pause when they reject a higher target. Only raise this limit to a speed verified to work on your fan. This does not change its permanent presets or measured-speed display."
             }
           },
           "required": [

package/docs/README.md

@@ -0,0 +1,18 @@
+# Project documentation
+
+The public guide is the [SvaraHome README](../README.md). [Release notes](../RELEASE_NOTES.md) and the [changelog](../CHANGELOG.md) describe the value and changes in 2.5; the changelog remains marked Unreleased until stable publication.
+
+## Current development references
+
+- [Validation](VALIDATION.md): what has been checked, with remaining acceptance limits.
+- [Verification readiness](VERIFICATION.md): evidence against Homebridge’s requirements and work before submission.
+- [Stable promotion](STABLE-PROMOTION.md): publication and actual Homebridge link acceptance checks.
+- [Release writing](RELEASING.md): the owner’s rules for public release copy.
+- [Link audit](LINK-AUDIT.md): homepage metadata behaviour and subsequent corrections.
+- [Artwork](BRANDING.md): provenance and the approved visual identity.
+
+## Historical evidence
+
+[BETA1-LIVE-DIAGNOSTIC.md](BETA1-LIVE-DIAGNOSTIC.md), the [redacted control records](pi-live-control-evidence-20261025.jsonl), dependency audits, native-install records, TAP logs and package manifests are snapshots from specific builds and investigations. Their filenames, test counts and earlier acceptance gaps describe those checks at that time; they are not the current user guide or guarantees about every fan.
+
+The current validation summary takes precedence when assessing present coverage. Prior published packages and release copy remain available through their immutable tags and GitHub prereleases. Preserve evidence; do not copy the investigation narrative into user-facing release notes.

package/docs/VALIDATION.md

@@ -1,8 +1,16 @@
 # SvaraHome 2.5 validation
 
-## Current code evidence
+## 2.5.1 patch acceptance
 
-The runtime on the default branch is the tested beta.3 implementation (release commit 3f4066177868d7a651c8400803c3f490f21d471b). Later repository cleanup changes documentation, not runtime behaviour.
+The only runtime change from 2.5.0 is a conservative 2400 RPM default ceiling for temporary Boost and slider targets when no explicit per-fan limit is set. Explicit limits and measured RPM remain unchanged. Both tested fans accepted 2400 RPM; Kitchen and Wetroom returned Pause for 2450 RPM. This is a conservative compatibility default, not a universal firmware maximum.
+
+The current suite has 60 tests, including the default ceiling, explicit higher/lower limits, unchanged measured speed, numeric HomeKit writes and persistent Pause On/Off retries. Node 24.19.0 local acceptance passes with Homebridge 1.11.4 and 2.4.0. The publication gate also requires the Node 22/24 × Homebridge 1/2 workflow to pass native load, full/production audits, syntax, tests and package checks on the release commit.
+
+Live Pause/resume trials on 26 October passed on both fans; Kitchen recovered after a failed initial request without a repeated command. Both ended in automatic ventilation with no pending command. The existing Kitchen CO2 automation action achieved Boost after the speed correction. These hardware trials validate the 2400 RPM target and unchanged Pause/retry path; they do not constitute installing 2.5.1 on the Pi or observing a fresh natural CO2 trigger.
+
+## 2.5.0 baseline evidence
+
+The 2.5.0 runtime was the tested beta.3 implementation (release commit 3f4066177868d7a651c8400803c3f490f21d471b). Later repository cleanup changes documentation, not runtime behaviour.
 
 All 52 tests passed in each Node 22/24 × Homebridge 1/2 combination in [release CI run 40220445646](https://github.com/KernowekConsulting/homebridge-pax-calima/actions/runs/40220445646). The jobs also passed native installation/loading, full and production security audit gates, syntax and package checks.
 

package/docs/VERIFICATION.md

@@ -1,6 +1,10 @@
 # Homebridge verification readiness
 
-Reviewed 26 October 2026 against the current requirements and request forms. SvaraHome is not verified, and no verification request has been submitted by this work.
+Reviewed 26 October 2026 against the current requirements and request forms. **Stable 2.5.0 is published and [verification request #1302](https://github.com/homebridge/plugins/issues/1302) has been submitted. Verification has not yet been granted.**
+
+The exact stable release commit passed all four [Node 22/24 × Homebridge 1/2 CI jobs](https://github.com/KernowekConsulting/homebridge-pax-calima/actions/runs/40297202771), with 52 tests per job. npm latest is 2.5.0; the downloaded public tarball matched the checked artifact. The rendered default npm page shows the cleaned guide and correct homepage. The actual Homebridge Plugin Homepage button was followed to the intended HTTPS site, whose stable 2.5.0 copy rendered in Safari. GitHub release notes match the approved file. The Homebridge update-dialog release-note view was not separately inspected while the owner was using that window.
+
+The assessment below retains the development evidence and earlier preparation history; the stable publication and submitted request above supersede its pending-promotion references.
 
 ## Assessment
 
@@ -34,7 +38,7 @@ Beta.3 simplifies the default presentation to Fan and Boost Fan; Pause Fan is op
 - Kitchen transient failures recovered without repeating the Home command. Final trials ended with both manual overrides Off and no pending requests. See [the detailed live report](BETA1-LIVE-DIAGNOSTIC.md) and [42 redacted trial records](pi-live-control-evidence-20261025.jsonl).
 - Dependency remediation and isolated installation details are in [DEPENDENCY-SECURITY.md](DEPENDENCY-SECURITY.md). The beta implementation uses the maintained Noble fork; stable 2.4.5 still has the old dependency.
 
-## Remaining work before requesting review
+## Earlier remaining-work list (historical)
 
 1. Complete the owner's chosen full 2.5.0 promotion, including final version/source alignment, review of the concise user-facing release copy and removal of the changelog’s Unreleased label. The owner declined a metadata-only 2.4.6 release.
 2. Follow [STABLE-PROMOTION.md](STABLE-PROMOTION.md): verify npm latest metadata, the actual Homebridge Plugin Homepage button and release-note view after cache refresh. Beta.2's homepage is correct, but the UI currently uses stable 2.4.5 metadata. Preserve a GitHub issue tracker so release-note discovery still works.

package/lib/accessory.js

@@ -2,6 +2,9 @@
 const { check, bytes, FanError, publicError, decodeStatus, decodeManual, encodeManual,
   verifyManual, decodeSilent, configuredSchedule, MAX_RPM } = require('./protocol');
 const POLL_MS = 10000, STALE_MS = 45000;
+// Both tested fans turn a rejected 2450 RPM request into Pause. Use the
+// verified 2400 target by default; explicit per-fan limits remain available.
+const DEFAULT_MANUAL_MAX_RPM = 2400;
 const RETRYABLE = new Set(['BLE_OPERATION_FAILED', 'BLE_TIMEOUT', 'BLE_RECOVERY_REQUIRED', 'BLE_UNAVAILABLE',
   'FAN_NOT_FOUND', 'SCAN_FAILED', 'SCAN_STOP_FAILED', 'BLUETOOTH_NOT_READY', 'BLUETOOTH_ERROR']);
 
@@ -179,7 +182,7 @@ class FanAccessory {
       // only its own kind, so a delayed Boost-off cannot cancel Pause.
       if (!on && (kind === 'automatic' ? current.state === 'automatic' : current.state !== kind)) return this.snapshot(io);
       const seconds = (kind === 'pause' ? this.config.pauseMinutes || 10 : this.config.boostMinutes || 10) * 60;
-      const target = kind === 'pause' ? 0 : Math.min(this.fan.maxManualRpm || MAX_RPM, rpm || this.config.boostRpm || 2000);
+      const target = kind === 'pause' ? 0 : Math.min(this.fan.maxManualRpm || DEFAULT_MANUAL_MAX_RPM, rpm || this.config.boostRpm || 2000);
       const value = on ? encodeManual(target, seconds) : Buffer.alloc(5);
       // A write may have reached the fan even if the response was lost. Adopt
       // its verified active timer rather than restarting it on every retry.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-pax-calima",
   "displayName": "SvaraHome",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "SvaraHome brings timed Boost, Pause and local Bluetooth control for Pax Calima and Vent-Axia Svara fans into Apple Home.",
   "main": "index.js",
   "keywords": [
@@ -61,5 +61,9 @@
   ],
   "dependencies": {
     "@stoprocent/noble": "2.8.0"
+  },
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://buymeacoffee.com/jayc68"
   }
 }