homebridge-pax-calima 2.5.2 → 2.6.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.6.0-beta.2
+
+- Made CO₂ Clear setup easier to follow, with a checklist for the two automations and help replacing an existing CO₂-to-Boost rule.
+- Clarified that ending CO₂ Clear hands back to the fan’s own ventilation, including its humidity response.
+- Brought speed and maximum running time together in Plugin Config, with the shorter fan timer under advanced settings.
+- Updated the included release notes to match SvaraHome’s everyday voice.
+- Kept existing controls, settings and beta.1 automations in place.
+
+## 2.6.0-beta.1
+
+- Added **CO₂ Clear**: extra ventilation when your sensor reports high CO₂, with a return to normal when it reports an acceptable level.
+- Kept you in control: using Fan, Boost or Pause takes priority over CO₂ Clear.
+- Added a choice of speed and maximum running time, with a one-hour default if the sensor's all-clear never arrives.
+- Added a setup guide for the two Home automations, recommending Controller for HomeKit for Netatmo's all-clear rule.
+- Added more detail to support logs to help investigate interrupted fan communication.
+
 ## 2.5.2
 
 - Now verified by Homebridge.

package/README.md

@@ -10,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** brings timed Boost, Pause and confirmed fan feedback to Apple Home.
+**Trial build: SvaraHome 2.6.0-beta.2.** Adds optional **CO₂ Clear**, alongside the existing timed Boost and Pause controls. Stable users should stay on `latest` (2.5.2); this beta is for a supervised trial. See the [CO₂ Clear beta guide](docs/CO2-CLEAR-BETA.md).
 
 ## What you get in Apple Home
 
@@ -18,6 +18,7 @@ SvaraHome brings local Bluetooth control for Pax Calima and Vent-Axia Svara fans
 | --- | --- |
 | **Fan** | Shows measured speed as a percentage. Off starts a timed pause; On returns either Pause or Boost to automatic ventilation. |
 | **Boost Fan** | Runs the fan at your chosen speed for a limited time. Turn it off to return sooner. Shown by default. |
+| **CO₂ Clear** | Extra ventilation between your sensor’s high and acceptable CO₂ events. Shown by default and initially Off. Set up both automations below. |
 | **Pause Fan** | Optional separate pause switch for status and automations. Hidden by default unless explicitly enabled. |
 | **Silent Hours** | Optional switch for the fan’s saved quiet-hours schedule. It does not start an immediate pause. |
 
@@ -29,6 +30,31 @@ The displayed speed comes from measured RPM. It can differ from the requested pe
 
 Temperature, humidity and light are **not exposed as ambient sensors**. SvaraHome does not provide a shower-detection sensor or infer room conditions from fan speed.
 
+## CO₂ Clear — give the room the time it needs
+
+CO₂ Clear links your CO₂ sensor and fan through two Home automations. It starts extra ventilation when CO₂ rises and hands back to the fan’s own automatic ventilation when the sensor gives the all-clear.
+
+**The fan can keep running for humidity after CO₂ Clear turns Off.** Off ends only CO₂ Clear’s extra ventilation. It does not pause the fan or disable its own humidity response. Using Fan, Boost or Pause yourself takes priority over CO₂ Clear.
+
+### Set up both automations
+
+1. Check that **CO₂ Clear** appears within the fan in Apple Home or Controller. If Controller still shows only Boost and Pause after an update, close and reopen Controller to refresh its list. Do not remove the fan or reset pairing.
+2. Create **CO₂ high → CO₂ Clear On**.
+3. Create **CO₂ acceptable → CO₂ Clear Off**. Select CO₂ Clear, not Fan Off or Pause.
+4. Disable the old CO₂-to-Boost automation once the new pair is ready, so it cannot interrupt CO₂ Clear. Keep a record of it if you want to return to timed Boost.
+
+For Netatmo’s all-clear rule we recommend **Controller for HomeKit**, an additional app that may require its own licence. Apple Home’s editor offers Netatmo’s high-CO₂ trigger, but not the matching all-clear trigger. Use Controller’s regular HomeKit automations; its separate Workflows or Controller Hub are not needed. Choose **Carbon dioxide Detected: Yes** for high and **No** for acceptable. Netatmo’s built-in high level is above 1600 ppm. Use that flag, not its combined Air Quality reading.
+
+Start with one sensor and one fan. The switch waits for your automations; SvaraHome does not read the sensor directly. Check both saved actions and then observe a real rise and return to acceptable CO₂. Creating the rules is the start of the trial, not proof that both sensor events arrive.
+
+### Choose what suits your home
+
+In Plugin Config, choose the speed and maximum time for extra ventilation. The defaults are 2400 RPM (96% on the Home speed scale) and one hour, respecting a lower limit set for an individual fan. The shorter fan timer sits under **CO₂ Clear — advanced timer** and normally stays at 15 minutes.
+
+If the all-clear never arrives, CO₂ Clear ends at the maximum time and returns to the fan’s automatic ventilation. That limit does not mean the room’s CO₂ has cleared. Sending On again during a session does not extend it. After the limit or a Homebridge restart, it waits for a new On request. An existing fan timer can continue briefly after a restart before returning to automatic ventilation.
+
+See the [CO₂ Clear setup and trial guide](https://github.com/KernowekConsulting/homebridge-pax-calima/blob/v2.6.0-beta.2/docs/CO2-CLEAR-BETA.md) for the full walkthrough and ways to return to your previous setup.
+
 ## Use your own words
 
 Assign each fan to its room in Apple Home. In a room named Kitchen, try:
@@ -85,6 +111,10 @@ The address and PIN are examples. Use your own fan’s details. A Bluetooth addr
 | `boostMinutes` / `boostRpm` | Temporary Boost duration and requested speed. Defaults: 10 minutes and 2000 RPM. |
 | `pauseMinutes` | Timed pause duration, including when the main Fan is turned off. Default: 10 minutes. |
 | `showBoostSwitch` | Show Boost Fan. Default: `true`. |
+| `co2ClearEnabled` | Show the separate CO₂ Clear demand control. Default: `true`; always initially Off. |
+| `co2ClearRpm` | Requested CO₂ Clear speed; default 2400 RPM, range 1000–2400 in 25 RPM steps, also limited by the fan ceiling. |
+| `co2ClearLeaseMinutes` | Finite fan timer renewed while demand is active; default 15, range 1–15 minutes. |
+| `co2ClearMaxMinutes` | Maximum demand session; default 60, range 1–240 minutes. Repeated On cannot extend it. |
 | `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 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. |
@@ -118,6 +148,6 @@ An explicitly enabled Pause switch remains enabled after upgrading. Turn off **S
 
 ## About the project
 
-SvaraHome is independent of Apple, Homebridge, Pax and Vent-Axia. **Homebridge verification has not yet been granted.** Homebridge controls the verification badge and central plugin icon; bundling the SvaraHome artwork does not grant either.
+SvaraHome is independent of Apple, Homebridge, Pax and Vent-Axia. **Homebridge verification was granted on 28 October 2026.** Homebridge controls the verification badge and central plugin icon; bundling the SvaraHome artwork does not grant either.
 
 For help, start with the [SvaraHome website](https://homebridge.svarahome.kernowekconsulting.co.uk) or [GitHub issues](https://github.com/KernowekConsulting/homebridge-pax-calima/issues). [Validation evidence](docs/VALIDATION.md) and [verification preparation](docs/VERIFICATION.md) are available separately.

package/RELEASE_NOTES.md

@@ -1,3 +1,27 @@
-# SvaraHome 2.5.2
+# SvaraHome 2.6.0-beta.2 — CO₂ Clear, clearer from the start
 
-Now verified by Homebridge.
+Extra ventilation when CO₂ rises. A little more help getting it ready.
+
+CO₂ Clear brings your sensor and fan together in Apple Home, giving the room more time for extra ventilation. This beta makes the setup easier to follow and the choices in Plugin Config clearer.
+
+## Two automations, one simple idea
+
+**CO₂ high → CO₂ Clear On.**
+
+**CO₂ acceptable → CO₂ Clear Off.**
+
+The guide now walks through both rules, finding the new control and replacing an existing CO₂-to-Boost automation. For Netatmo’s all-clear rule, we recommend Controller for HomeKit, an additional app.
+
+If you already set up both rules with beta.1, keep them. There is no need to create them again.
+
+## Humidity still has its say
+
+When CO₂ Clear ends, the fan returns to its own automatic ventilation. If the room is still humid, the fan can keep running as usual. The all-clear action ends CO₂ Clear’s extra ventilation; it does not pause the fan.
+
+## Choices that are easier to find
+
+Speed and maximum running time now sit together in Plugin Config. The shorter fan timer is tucked under advanced settings, where it can usually stay as it is.
+
+The defaults remain 96% and a one-hour maximum, within any lower limit you have chosen for your fan. Your ordinary Fan, Boost and Pause controls still take priority.
+
+Choose **2.6.0-beta.2** in Homebridge to try it. The [CO₂ Clear setup guide](https://github.com/KernowekConsulting/homebridge-pax-calima/blob/v2.6.0-beta.2/docs/CO2-CLEAR-BETA.md) has the walkthrough. We are continuing the everyday trial before a wider release; **2.5.2** remains the regular release.

package/config.schema.json

@@ -32,7 +32,7 @@
               "title": "Fan PIN",
               "type": "string",
               "pattern": "^(?:[0-9]{6}|[0-9]{8})$",
-              "description": "Enter this fan\u2019s six- or eight-digit PIN, including any leading zeroes. The PIN is stored in your Homebridge configuration.",
+              "description": "Enter this fan’s six- or eight-digit PIN, including any leading zeroes. The PIN is stored in your Homebridge configuration.",
               "secret": true
             },
             "maxManualRpm": {
@@ -42,7 +42,7 @@
               "maximum": 2500,
               "multipleOf": 25,
               "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."
+              "description": "Optional. Limits Boost, CO₂ Clear 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": [
@@ -97,13 +97,44 @@
         "title": "Quiet hours end",
         "type": "string",
         "placeholder": "06:00",
-        "description": "Use 24-hour time, such as 06:00. Leave both fields blank to retain the fan\u2019s existing schedule."
+        "description": "Use 24-hour time, such as 06:00. Leave both fields blank to retain the fan’s existing schedule."
       },
       "showSilentSwitch": {
         "title": "Show Silent Hours in Apple Home",
         "type": "boolean",
         "default": false,
-        "description": "Enable or disable the fan\u2019s saved quiet-hours schedule. This preserves its times; it does not start an immediate pause."
+        "description": "Enable or disable the fan’s saved quiet-hours schedule. This preserves its times; it does not start an immediate pause."
+      },
+      "co2ClearEnabled": {
+        "title": "Show CO₂ Clear in Apple Home",
+        "type": "boolean",
+        "default": true,
+        "description": "Extra ventilation when CO₂ rises. Set up two automations: CO₂ high → CO₂ Clear On; CO₂ acceptable → CO₂ Clear Off. For Netatmo, use Controller for HomeKit to create the all-clear rule. CO₂ Clear Off returns control to the fan’s own ventilation, including its humidity response. The switch starts Off and waits for an automation or your command."
+      },
+      "co2ClearRpm": {
+        "title": "Speed for extra ventilation (RPM)",
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 2400,
+        "multipleOf": 25,
+        "default": 2400,
+        "description": "2400 RPM is 96% on the Home speed scale. Any lower limit you have chosen for an individual fan still applies."
+      },
+      "co2ClearLeaseMinutes": {
+        "title": "Fan timer if Homebridge disconnects (minutes)",
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 15,
+        "default": 15,
+        "description": "Normally leave this at 15 minutes. While CO₂ Clear is active, SvaraHome keeps this short fan timer topped up. If Homebridge stops, the timer expires and the fan returns to its own automatic ventilation. This is separate from the maximum running time above."
+      },
+      "co2ClearMaxMinutes": {
+        "title": "Maximum time for extra ventilation (minutes)",
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 240,
+        "default": 60,
+        "description": "If the sensor’s all-clear never arrives, CO₂ Clear ends after this time and hands back to the fan’s own automatic ventilation. The default is one hour. Sending On again during a session does not extend it. After it ends or Homebridge restarts, a new On request is needed."
       }
     },
     "required": [
@@ -138,6 +169,24 @@
         "pauseMinutes"
       ]
     },
+    {
+      "type": "section",
+      "title": "CO₂ Clear — extra ventilation when CO₂ rises",
+      "items": [
+        "co2ClearEnabled",
+        "co2ClearRpm",
+        "co2ClearMaxMinutes"
+      ]
+    },
+    {
+      "type": "section",
+      "title": "CO₂ Clear — advanced timer",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "co2ClearLeaseMinutes"
+      ]
+    },
     {
       "type": "section",
       "title": "Quiet hours",

package/docs/CO2-CLEAR-BETA.md

@@ -0,0 +1,82 @@
+# CO₂ Clear — 2.6.0-beta.2 trial
+
+CO₂ Clear is a separate third control alongside timed Boost Fan and Pause Fan. It maintains a bounded ventilation request between High and Clear events. The existing fan accessory identities, room assignments and ordinary controls are retained.
+
+## Before you start
+
+CO₂ Clear needs a pair of Home automations: **CO₂ high → CO₂ Clear On**, and **CO₂ acceptable → CO₂ Clear Off**. Check both rules before relying on it.
+
+**CO₂ Clear Off ends extra ventilation, not ventilation needed for humidity.** The fan returns to its own automatic control and may keep running. Never use main Fan Off or Pause as the all-clear action: those request a timed pause. CO₂ Clear has no humidity measurement and does not change the fan’s humidity settings.
+
+If the new control is missing in Controller after an upgrade, close and reopen Controller first. That refreshed the accessory list during this trial without changing the fan, pairing or Homebridge. A stale third-party list is not a reason to reset accessories.
+
+In Plugin Config, the main CO₂ Clear section holds visibility, speed and maximum running time. The shorter disconnect timer is under the collapsed advanced-timer section. Saved settings and existing Home automations are retained when upgrading from beta.1; do not create duplicate rules if the correct pair already exists.
+
+## Required automation editor: decide before using this feature
+
+**Apple Home alone does not expose the Netatmo CO₂-clear automation event. For this beta we explicitly recommend Controller for HomeKit to create that rule.** Controller is an additional app; check its current licensing and Home access requirements. This is an optional feature dependency, not an assumption that customers already have it. Ordinary timed Boost and Pause need neither Controller nor a CO₂ sensor.
+
+Use the regular **HomeKit Automations** editor, not Controller Workflows. These are HomeKit rules for the existing Apple Home hub; this design does not require a separate Controller Hub or SvaraHome cloud account. Other editors are not validated by this beta.
+
+On 30 October, read-only inspection of the owner's Netatmo Kitchen Climate showed:
+
+- Apple Home's CO₂ event editor offers only **Detects High Carbon Dioxide**.
+- Controller's editor exposes **Carbon dioxide Detected = No** as a **Value is** start event. At inspection the sensor reported No and 916 ppm.
+- Both inspections were cancelled without saving rules or sending fan commands.
+
+This establishes an editable clear rule and a readable normal state, not delivery of a real high-to-normal notification. That transition must be demonstrated during the live trial. Netatmo's [official HomeKit guide](https://helpcenter.netatmo.com/hc/en-us/articles/360010067180-What-can-you-do-with-a-Station-paired-with-Apple-HomeKit) documents detected/high above **1600 ppm**. The owner chose to retain this built-in flag, with no custom 1500 ppm threshold. A warning notification and a characteristic state-change event are different things; no separate normal notification banner is required for an automation.
+
+## Rules to configure for the trial
+
+First install the beta and confirm both ordinary controls remain functional. Check the fan and room, verify the High scene contains only CO₂ Clear On and the Clear scene only CO₂ Clear Off, and confirm both rules are enabled without unintended time or presence restrictions. Do not run an existing CO₂-to-Boost rule alongside the new CO₂ Clear rule: the newer ordinary Boost command would intentionally take priority and cancel CO₂ Clear renewal. Record the old rule so it can be restored for rollback.
+
+For **one CO₂ sensor and one fan**:
+
+1. **High:** Kitchen Carbon Dioxide Sensor detects High → Kitchen CO₂ Clear On. Apple Home's existing High trigger is suitable. Leave Home's delayed **Turn Off** timer disabled for this CO₂ Clear rule; the Clear rule and plugin session limit handle termination.
+2. **Clear:** in Controller → Automations → Add Start Event → Accessory → Kitchen Climate → Carbon Dioxide Sensor → **Carbon dioxide Detected** → **Value is No**. Action: Kitchen **CO₂ Clear Off**. Select the CO₂ Clear switch, not Fan Off (which would pause ventilation). Create/save the rule only as part of the agreed trial setup.
+3. Review both rules, the selected Home, fan and sensor, and any time/presence restrictions. A sensor that is already High at setup will not necessarily produce a new High transition; a deliberate manual CO₂ Clear trial is separate from a real sensor-trigger test.
+
+Use the Detected flag, not **Air Quality**. Netatmo's Air Quality combines CO₂, temperature and humidity and is not an equivalent CO₂-clear measurement. The MVP does not aggregate multiple sensors: several independent Clear rules could clear another sensor's active demand. Multi-sensor demand arbitration is deferred.
+
+## Settings and behaviour
+
+| Setting | Default | Allowed values |
+|---|---:|---|
+| co2ClearEnabled | true | true/false; shows the third switch, initially Off |
+| co2ClearRpm | 2400 | 1000–2400 RPM, steps of 25; also capped by each fan's maxManualRpm |
+| co2ClearLeaseMinutes | 15 | 1–15 minutes |
+| co2ClearMaxMinutes | 60 | 1–240 minutes |
+
+2400 RPM is 96% on the plugin's 2500 RPM display scale. Measured motor speed remains a separate reading. CO₂ Clear starts a finite fan timer, confirms its readback, and renews halfway through the reported remaining time. The last timer is shortened to the remaining maximum-session budget. Repeated On does not restart or extend that maximum session. Boost's ordinary duration/speed configuration remains separate.
+
+CO₂ Clear On means the demand session is armed; it is not a CO₂ reading or a claim that every Bluetooth operation succeeded. Failed commands retain existing communication-error/retry behaviour. Receipt, pending/retry, confirmed timer, renewal, cancellation and cap events are logged. A Clear/Off stops renewal immediately and requests release of its owned override. The existing Boost/Pause switches and measured speed show actual verified fan state; demand Off alone is not proof that the release command has reached the fan.
+
+Manual Fan On/Off, Boost, Pause or speed-slider commands cancel CO₂ Clear renewal and take priority. A later CO₂ Clear Off does not cancel those replacement requests. Recognisable native-app changes (Pause, a different boost speed, or early return to automatic) also end demand. The BLE protocol has no ownership tag: an out-of-band app command with the identical speed/timer cannot always be distinguished. Avoid simultaneous control from the native app during the beta test.
+
+## Missing sensor, restart and maximum session
+
+The plugin **does not poll Apple Home or the sensor** and cannot determine freshness from a latched High. If the sensor/network/Home hub fails before Clear, CO₂ Clear keeps renewing only within its configured maximum session. At that limit it turns demand Off and requests automatic ventilation, even if CO₂ has not cleared. It does not report that the air is acceptable. A new explicit On is required to start another session; old High is not replayed automatically.
+
+If Homebridge shuts down, renewals stop; the last finite fan timer expires naturally within the configured lease. Restart never restores a previous High or an air-renewal request. A pending ordinary Boost/Pause request retains its existing restart behaviour. A pending CO₂ Clear release is not retried indefinitely: its cleanup window is bounded by a lease, after which the native timer is the fallback. A command already dispatched over BLE can complete after a newer demand arrives; the queued latest request reconciles that state.
+
+Switching CO₂ Clear off in configuration removes its control and stops future renewals after the child restart. An existing fan timer can run to expiry. Do not hide the control before reviewing the Home rules that reference it.
+
+## Proposed supervised checks
+
+These are trial steps, not claims of tests already performed on live fans:
+
+1. Preserve configuration and exact installed 2.5.2 package/source, record its checksums and confirm a source-only recovery route. Preserve cached accessories and room identities; do not reset pairing.
+2. Install the beta only on SvaraHome and restart only its child bridge when authorised. Check startup version/source fingerprints, both connections, unchanged Boost/Pause service identities, CO₂ Clear initially Off and no old demand re-armed.
+3. For a shorter observation, set a one-minute lease and three-minute maximum session, retain the verified RPM ceiling, then manually send CO₂ Clear On. Confirm the initial native timer, at least two renewals beyond its first expiry, Off release and return to automatic via readback. Restore the intended 15/60-minute settings afterwards with the agreed child restart.
+4. Test manual Pause during demand, then a delayed Clear: Pause must remain in force. Verify ordinary Boost and Fan On still work and that the old air renewal cannot reappear.
+5. With a native humidity demand present, verify that CO₂ Clear Off releases only its own extra ventilation and leaves automatic humidity ventilation available. Readback returning to automatic is the check; a stopped motor is not required. If CO₂ Clear has never been On, an Off should not send a fan command.
+6. Correlate a natural High transition with receipt and confirmed fan timer. Then correlate the actual Detected Yes→No transition with CO₂ Clear Off receipt and confirmed release. Home's Test Automation action proves only that rule's action path, not the real sensor transition. Do not manufacture CO₂ exposure or falsify readings.
+7. Observe source loss/missing Clear and the maximum-session cutoff, plus a bounded restart check. Do not disrupt the live Home hub, Pi radio or other plugins to manufacture a failure without a separate agreed test.
+
+The owner's Netatmo network instability remains an upstream fault. This beta does not repair it or the underlying Bluetooth discovery failures. The existing patient retries remain; no unproven wake delay, adapter reset, new sensor API or changed PIN handling is included.
+
+## Rollback
+
+Stop CO₂ Clear and confirm its native manual override is released, or allow the finite lease to expire if it cannot be reached. Disable only the new High/Clear rules. Restore the exact backed-up stable plugin/configuration, preserving Homebridge accessory cache and fan identities, and restart only the SvaraHome child bridge. Confirm both fans reconnect and no CO₂ Clear renewal survives. Restore the prior CO₂-to-timed-Boost rule only after confirming the beta rules are disabled. Returning to stable removes the new CO₂ Clear service, so its Home rules need to remain disabled or be deleted deliberately.
+
+No beta package installation, fan commands or Home rule changes were performed while preparing this build. The owner is independently updating stable 2.5.2. Beta publication, trial installation and live control checks must be separately recorded; automated tests are not live acceptance.

package/docs/VERIFICATION.md

@@ -1,3 +1,9 @@
+# Current verification status
+
+Homebridge verified SvaraHome on 28 October 2026 after checks against 2.5.1. See the [maintainer confirmation](https://github.com/homebridge/plugins/issues/1302#issuecomment-6480171817) and [official register](https://github.com/homebridge/plugins/blob/master/verified-plugins.json). Stable 2.5.2 records that status. This beta adds unvalidated live behaviour; verification is not a guarantee of a particular automation or Bluetooth connection.
+
+The dated readiness review below is retained as historical evidence; references there to pending verification are superseded by the confirmation above.
+
 # Homebridge verification readiness
 
 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.**

package/lib/accessory.js

@@ -1,6 +1,8 @@
 'use strict';
 const { check, bytes, FanError, publicError, decodeStatus, decodeManual, encodeManual,
   verifyManual, decodeSilent, configuredSchedule, MAX_RPM } = require('./protocol');
+const { failureDetails } = require('./transport');
+const { CO2Clear } = require('./co2-clear');
 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.
@@ -14,12 +16,14 @@ class FanAccessory {
     this.config = platform.config; this.last = null; this.fault = true; this.closed = false;
     this.pollPending = false; this.errorCode = null; this.controls = [];
     this.intent = null;
+    this.loggedDiagnostics = new WeakSet();
     const saved = accessory.context.pendingManual;
     if (saved && ['boost', 'pause', 'automatic'].includes(saved.kind) && typeof saved.on === 'boolean' &&
         (saved.kind !== 'automatic' || (saved.on === false && saved.rpm === undefined)) &&
         (saved.rpm === undefined || (Number.isInteger(saved.rpm) && saved.rpm >= 1000 && saved.rpm <= MAX_RPM && saved.rpm % 25 === 0))) {
       this.intent = { kind: saved.kind, on: saved.on, rpm: saved.rpm, attempted: saved.attempted === true };
     }
+    this.co2Clear = new CO2Clear(this);
     this.setup();
   }
   hapError() { return new this.hap.HapStatusError(this.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE); }
@@ -60,6 +64,8 @@ class FanAccessory {
       s => s.manual.state === 'boost', value => this.manual('boost', value));
     this.pauseService = this.switchService('pause', 'Pause Fan', this.config.showPauseSwitch === true,
       s => s.manual.state === 'pause', value => this.manual('pause', value));
+    this.co2ClearService = this.switchService('co2-clear', 'CO₂ Clear', this.co2Clear.enabled,
+      () => this.co2Clear.active, value => this.co2Clear.set(value));
     this.silentService = this.switchService('silent-hours', 'Silent Hours', this.config.showSilentSwitch === true,
       s => s.silent.enabled, value => this.silent(value));
     const info = a.getService(S.AccessoryInformation);
@@ -126,17 +132,24 @@ class FanAccessory {
     try { await action(); }
     catch (error) { if (publicError(error) !== 'COMMAND_SUPERSEDED') this.fail(error); throw this.hapError(); }
   }
-  async manual(kind, on, rpm) {
+  async manual(kind, on, rpm, owner) {
     check(['boost', 'pause', 'automatic'].includes(kind) && typeof on === 'boolean' &&
       (kind !== 'automatic' || (on === false && rpm === undefined)), 'INVALID_COMMAND');
+    if (!owner) this.co2Clear.abandon('manual control takes priority');
+    if (this.intent) this.logIntent(this.intent, 'replaced by a newer command');
     // Replacing the object invalidates any older queued attempt before its write.
     clearTimeout(this.intentTimer); this.intentTimer = null;
-    const intent = { kind, on, rpm, attempted: false };
+    const intent = { kind, on, rpm, attempted: false, owner };
     this.intent = intent; this.saveIntent();
+    this.logIntent(intent, 'received');
     return this.attemptIntent(intent);
   }
+  logIntent(intent, outcome) {
+    this.platform.log.info('SvaraHome ' + this.accessory.displayName + ': ' + intent.kind + ' ' +
+      (intent.on ? 'On' : 'Off') + ' request ' + outcome + '.');
+  }
   saveIntent() {
-    if (this.intent) {
+    if (this.intent && !this.intent.owner) {
       const { kind, on, rpm, attempted } = this.intent;
       this.accessory.context.pendingManual = { kind, on, rpm, attempted };
     } else delete this.accessory.context.pendingManual;
@@ -155,10 +168,17 @@ class FanAccessory {
     intent.running = true;
     try {
       await this.applyManual(intent);
-      if (this.intent === intent) { this.intent = null; this.saveIntent(); }
+      if (this.intent === intent) {
+        if (!this.closed && this.last) {
+          const state = this.last.manual;
+          this.logIntent(intent, 'confirmed; fan reports ' + state.state + ' ' + state.rpm + ' RPM/' + state.seconds + 's');
+        }
+        this.intent = null; this.saveIntent();
+        if (intent.owner) this.co2Clear.confirmed(intent);
+      }
     } catch (error) {
       if (!this.closed && this.intent === intent) {
-        this.fail(error);
+        if (publicError(error) !== 'COMMAND_SUPERSEDED') this.fail(error);
         if (RETRYABLE.has(publicError(error))) {
           this.scheduleIntent(intent);
           if (!intent.announced) {
@@ -166,7 +186,11 @@ class FanAccessory {
               ' request pending; retrying until confirmed or replaced by a newer command.');
             intent.announced = true;
           }
-        } else { this.intent = null; this.saveIntent(); }
+        } else {
+          this.logIntent(intent, 'stopped: ' + publicError(error));
+          this.intent = null; this.saveIntent();
+          if (intent.owner) this.co2Clear.failed(intent, publicError(error));
+        }
       }
       throw error;
     } finally { intent.running = false; }
@@ -174,14 +198,16 @@ class FanAccessory {
   async applyManual(intent) {
     const { kind, on, rpm } = intent;
     const result = await this.session(async io => {
-      check(this.intent === intent, 'COMMAND_SUPERSEDED');
+      check(this.currentIntent(intent), 'COMMAND_SUPERSEDED');
       const mode = bytes(await io.read('mode'), 1)[0];
       check(mode === 0, 'CONTROL_REQUIRES_MULTIMODE');
       const current = decodeManual(await io.read('manual'));
+      if (intent.owner && !on && !this.co2Clear.canRelease(intent, current)) return this.snapshot(io);
       // Fan On clears either override. Individual switch-off still affects
       // 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 seconds = intent.owner && on ? this.co2Clear.seconds(intent) :
+        (kind === 'pause' ? this.config.pauseMinutes || 10 : this.config.boostMinutes || 10) * 60;
       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
@@ -189,8 +215,9 @@ class FanAccessory {
       if (intent.attempted && on && current.state === kind && current.rpm === value.readUInt16LE(1) && current.seconds <= seconds) {
         return this.snapshot(io);
       }
-      check(this.intent === intent, 'COMMAND_SUPERSEDED');
+      check(this.currentIntent(intent), 'COMMAND_SUPERSEDED');
       intent.attempted = true; this.saveIntent();
+      if (intent.owner) this.co2Clear.willWrite(intent, seconds);
       await io.write('manual', value);
       const actual = await io.read('manual');
       try { verifyManual(actual, value); }
@@ -206,6 +233,9 @@ class FanAccessory {
     });
     this.publish(result); this.schedule(2000);
   }
+  currentIntent(intent) {
+    return !this.closed && this.intent === intent && (!intent.owner || this.co2Clear.valid(intent));
+  }
   speed(percent) {
     check(typeof percent === 'number' && Number.isFinite(percent) && percent >= 0 && percent <= 100, 'INVALID_SPEED');
     if (percent === 0) return this.manual('pause', true);
@@ -228,6 +258,7 @@ class FanAccessory {
   publish(state) {
     if (this.closed) return;
     this.last = state; this.fault = false; this.authRejected = false;
+    this.co2Clear.observe(state);
     if (this.errorCode) this.platform.log.info('SvaraHome ' + this.accessory.displayName + ': communication restored.');
     this.errorCode = null;
     for (const { characteristic, get } of this.controls) characteristic.updateValue(get(state));
@@ -237,6 +268,20 @@ class FanAccessory {
   fail(error, polling = false) {
     if (this.closed) return;
     const code = publicError(error);
+    const detail = failureDetails(error);
+    if (detail && !this.loggedDiagnostics.has(detail)) {
+      this.loggedDiagnostics.add(detail);
+      const key = code + ':' + detail.stage;
+      // Commands retain every failed attempt. Repeated background failures at
+      // the same stage are sampled once a minute to keep evidence bounded.
+      if (!polling || !this.lastDiagnostic || this.lastDiagnostic.key !== key || Date.now() - this.lastDiagnostic.at >= 60000) {
+        this.platform.log.info('SvaraHome ' + this.accessory.displayName + ': Bluetooth attempt ' + detail.attempt +
+          ' failed; operation=' + (polling ? 'poll' : 'command') + '; code=' + code + '; stage=' + detail.stage +
+          '; stageMs=' + detail.stageMs + '; sessionMs=' + detail.sessionMs + '; queueMs=' + detail.queueMs +
+          '; lastCompleted=' + detail.completed + '.');
+        this.lastDiagnostic = { key, at: Date.now() };
+      }
+    }
     // A missed background poll need not flicker Home to No Response. Keep
     // the last verified snapshot only within the existing freshness limit.
     // Authentication, malformed telemetry and failed commands still fault.
@@ -245,6 +290,7 @@ class FanAccessory {
     // Do not repeatedly submit a known-rejected PIN during unattended polling.
     // A user command can explicitly retry, or a config restart can replace it.
     if (code === 'AUTH_REJECTED') {
+      this.co2Clear.abandon('authentication rejected');
       this.authRejected = true; clearTimeout(this.pollTimer); clearTimeout(this.intentTimer); this.intentTimer = null;
       if (this.intent) { this.intent = null; this.saveIntent(); }
     }
@@ -253,6 +299,9 @@ class FanAccessory {
     this.errorCode = code;
     if (!fresh) for (const { characteristic } of this.controls) characteristic.updateValue(this.hapError());
   }
-  close() { this.closed = true; clearTimeout(this.pollTimer); clearTimeout(this.staleTimer); clearTimeout(this.intentTimer); }
+  close() {
+    this.closed = true; this.co2Clear.close();
+    clearTimeout(this.pollTimer); clearTimeout(this.staleTimer); clearTimeout(this.intentTimer);
+  }
 }
 module.exports = { FanAccessory, POLL_MS, STALE_MS };

package/lib/co2-clear.js

@@ -0,0 +1,157 @@
+'use strict';
+const { performance } = require('node:perf_hooks');
+const { check } = require('./protocol');
+
+// Home supplies demand transitions; this controller has no sensor credentials,
+// sensor polling or knowledge of whether a latched High signal is still fresh.
+class CO2Clear {
+  constructor(host) {
+    this.host = host;
+    this.enabled = host.config.co2ClearEnabled !== false;
+    this.now = host.platform.co2ClearNow || (() => performance.now());
+    this.current = null;
+    this.sequence = 0;
+    if (host.accessory.context.co2ClearLease) {
+      delete host.accessory.context.co2ClearLease;
+      host.platform.save(host.accessory);
+      this.log('restart detected; renewal remains Off; any previous fan timer will expire naturally');
+    }
+  }
+  get active() { return Boolean(this.current && this.current.active); }
+  log(message) { this.host.platform.log.info('SvaraHome ' + this.host.accessory.displayName + ': CO2 Clear ' + message + '.'); }
+  update() {
+    if (this.host.co2ClearService) this.host.co2ClearService.getCharacteristic(this.host.hap.Characteristic.On)
+      .updateValue(this.host.fault ? this.host.hapError() : this.active);
+  }
+  async set(on) {
+    check(typeof on === 'boolean', 'INVALID_COMMAND');
+    check(this.enabled && !this.host.closed, 'CO2_CLEAR_DISABLED');
+    if (!on) return this.stop('acceptable/Off signal');
+    check(this.host.fan && this.host.platform.transport, 'FAN_NOT_CONFIGURED');
+    if (this.active) {
+      // Repeated On must never refresh the maximum session deadline.
+      if (this.host.intent && this.host.intent.owner === this.current) {
+        check(!this.host.intent.running, 'BLE_UNAVAILABLE');
+        return this.host.attemptIntent(this.host.intent);
+      }
+      check(!this.host.fault, 'BLE_UNAVAILABLE');
+      return;
+    }
+    this.abandon('replaced by a new air demand');
+    const token = {
+      active: true, sequence: ++this.sequence, mayOwn: false,
+      rpm: Math.min(this.host.fan.maxManualRpm || 2400, this.host.config.co2ClearRpm || 2400),
+      leaseSeconds: (this.host.config.co2ClearLeaseMinutes || 15) * 60,
+      end: this.now() + (this.host.config.co2ClearMaxMinutes || 60) * 60000,
+    };
+    this.current = token;
+    token.capTimer = setTimeout(() => {
+      if (this.current === token) this.stop('maximum session reached').catch(() => {});
+    },
+      Math.max(0, token.end - this.now()));
+    this.log('High/On signal received; session ' + token.sequence + ' armed with a finite limit');
+    this.update();
+    return this.host.manual('boost', true, token.rpm, token);
+  }
+  valid(intent) {
+    const token = intent.owner;
+    return this.current === token && (intent.on ? token.active && this.now() < token.end :
+      !token.active && token.releasing && this.now() < token.releaseEnd);
+  }
+  seconds(intent) {
+    check(this.valid(intent), 'COMMAND_SUPERSEDED');
+    const seconds = Math.min(intent.owner.leaseSeconds, Math.floor((intent.owner.end - this.now()) / 1000));
+    check(seconds >= 1, 'COMMAND_SUPERSEDED');
+    return seconds;
+  }
+  willWrite(intent, seconds) {
+    if (!intent.on) return;
+    intent.owner.mayOwn = true; // An acknowledged write can still lose its readback.
+    intent.owner.lastLeaseSeconds = seconds;
+    this.host.accessory.context.co2ClearLease = true;
+    this.host.platform.save(this.host.accessory);
+  }
+  canRelease(intent, current) {
+    // Do not clear a Pause or a recognisably different native/app override.
+    // The fan protocol cannot distinguish identical out-of-band Boost writes.
+    return intent.owner.mayOwn && current.state === 'boost' && current.rpm === intent.owner.rpm &&
+      current.seconds <= intent.owner.lastLeaseSeconds;
+  }
+  confirmed(intent) {
+    if (!this.valid(intent)) return;
+    const token = intent.owner, state = this.host.last.manual;
+    if (!intent.on) {
+      this.log('release confirmed; fan reports ' + state.state);
+      this.abandon();
+      return;
+    }
+    token.expectedEnd = this.now() + state.seconds * 1000;
+    this.log('session ' + token.sequence + ' confirmed at ' + state.rpm + ' RPM/' + state.seconds + 's');
+    clearTimeout(token.renewTimer);
+    token.renewTimer = setTimeout(() => {
+      if (this.current !== token || !token.active) return;
+      if (this.now() >= token.end) { this.stop('maximum session reached').catch(() => {}); return; }
+      this.log('session ' + token.sequence + ' renewing timed ventilation');
+      this.host.manual('boost', true, token.rpm, token).catch(() => {});
+    }, Math.max(1000, state.seconds * 500));
+  }
+  failed(intent, code) {
+    if (this.current !== intent.owner) return;
+    this.log('stopped after ' + code + '; no further renewal');
+    this.abandon();
+  }
+  observe(state) {
+    const token = this.current;
+    if (!token || !token.active || !token.mayOwn) return;
+    const manual = state.manual;
+    if (manual.state === 'pause' || (manual.state === 'boost' && manual.rpm !== token.rpm) ||
+      (manual.state === 'automatic' && token.expectedEnd && this.now() < token.expectedEnd - 3000)) {
+      this.abandon('native/manual control changed');
+    }
+  }
+  async stop(reason) {
+    const token = this.current;
+    if (!token) return; // An unrelated timed Boost or Pause must be left alone.
+    if (!token.active && token.releasing) {
+      if (this.host.intent && this.host.intent.owner === token && !this.host.intent.running)
+        return this.host.attemptIntent(this.host.intent);
+      return;
+    }
+    token.active = false;
+    clearTimeout(token.capTimer); clearTimeout(token.renewTimer);
+    this.log(reason + '; renewal Off');
+    this.update();
+    if (!token.mayOwn) { this.abandon(); return; }
+    token.releasing = true;
+    token.releaseEnd = this.now() + token.leaseSeconds * 1000;
+    token.cleanupTimer = setTimeout(() => {
+      if (this.current === token) this.abandon('release window ended; relying on the finite native timer');
+    }, token.leaseSeconds * 1000);
+    return this.host.manual('boost', false, undefined, token);
+  }
+  abandon(reason) {
+    const token = this.current;
+    if (!token) return;
+    token.active = false;
+    for (const key of ['capTimer', 'renewTimer', 'cleanupTimer']) clearTimeout(token[key]);
+    this.current = null;
+    if (this.host.intent && this.host.intent.owner === token) {
+      this.host.logIntent(this.host.intent, 'replaced by CO2 Clear cancellation');
+      clearTimeout(this.host.intentTimer); this.host.intentTimer = null;
+      this.host.intent = null; this.host.saveIntent();
+    }
+    delete this.host.accessory.context.co2ClearLease;
+    this.host.platform.save(this.host.accessory);
+    if (reason) this.log(reason + '; renewal Off');
+    this.update();
+  }
+  close() {
+    const token = this.current;
+    if (!token) return;
+    for (const key of ['capTimer', 'renewTimer', 'cleanupTimer']) clearTimeout(token[key]);
+    token.active = false; this.current = null;
+    // Preserve only a marker, never a resumable High or pending renewal.
+    this.log('bridge stopping; no further renewal; native timer remains bounded');
+  }
+}
+module.exports = { CO2Clear };

package/lib/platform.js

@@ -4,6 +4,15 @@ const { FanError, check, publicError, configuredSchedule, encodePin } = require(
 const { FanAccessory } = require('./accessory');
 const PLUGIN = 'homebridge-pax-calima';
 const MAC = /^(?:[0-9a-f]{2}:){5}[0-9a-f]{2}$/;
+function runtimeIdentity() {
+  const { createHash } = require('node:crypto'), { readFileSync } = require('node:fs');
+  const { join } = require('node:path');
+  const files = ['accessory.js', 'transport.js', 'co2-clear.js'];
+  return 'version=' + require('../package.json').version + '; ' + files.map(name => {
+    try { return name + '=' + createHash('sha256').update(readFileSync(join(__dirname, name))).digest('hex').slice(0, 12); }
+    catch (_) { return name + '=unavailable'; }
+  }).join('; ');
+}
 
 function validateConfig(config) {
   const fans = new Map();
@@ -28,6 +37,12 @@ function validateConfig(config) {
     if (config[key] !== undefined) check(Number.isInteger(config[key]) && config[key] >= 1 && config[key] <= 60, 'INVALID_DURATION');
   }
   if (config.boostRpm !== undefined) check(Number.isInteger(config.boostRpm) && config.boostRpm >= 1000 && config.boostRpm <= 2500 && config.boostRpm % 25 === 0, 'INVALID_SPEED');
+  if (config.co2ClearEnabled !== undefined) check(typeof config.co2ClearEnabled === 'boolean', 'INVALID_CO2_CLEAR_CONFIG');
+  for (const [key, max] of [['co2ClearLeaseMinutes', 15], ['co2ClearMaxMinutes', 240]]) {
+    if (config[key] !== undefined) check(Number.isInteger(config[key]) && config[key] >= 1 && config[key] <= max, 'INVALID_CO2_CLEAR_CONFIG');
+  }
+  if (config.co2ClearRpm !== undefined) check(Number.isInteger(config.co2ClearRpm) && config.co2ClearRpm >= 1000 &&
+    config.co2ClearRpm <= 2400 && config.co2ClearRpm % 25 === 0, 'INVALID_CO2_CLEAR_CONFIG');
   configuredSchedule(config.silentHoursStart, config.silentHoursEnd);
   return fans;
 }
@@ -42,7 +57,9 @@ function createPlatform(homebridge, dependencies = {}) {
         for (const code of this.fans.issues) this.log.warn('SvaraHome skipped fan setup: ' + code + '. Check its address and PIN in Plugin Config.');
       }
       catch (error) {
-        this.log.warn('SvaraHome setup needs attention: ' + publicError(error) + '. Check each fan address and its six- or eight-digit PIN in Plugin Config.');
+        const code = publicError(error);
+        this.log.warn('SvaraHome setup needs attention: ' + code + (code === 'INVALID_CO2_CLEAR_CONFIG' ?
+          '. Check CO2 Clear settings in Plugin Config.' : '. Check each fan address and its six- or eight-digit PIN in Plugin Config.'));
       }
       api.on('didFinishLaunching', () => this.launch());
       api.on('shutdown', () => this.shutdown());
@@ -54,6 +71,7 @@ function createPlatform(homebridge, dependencies = {}) {
     launch() {
       if (this.launched || this.stopped) return;
       this.launched = true;
+      if (this.log.info) this.log.info('SvaraHome runtime ' + runtimeIdentity() + '.');
       // Retain cached identities but fault them when config cannot be routed.
       for (const [mac, accessory] of this.cached) {
         const fan = this.valid && this.fans.get(mac);
@@ -95,4 +113,4 @@ function createPlatform(homebridge, dependencies = {}) {
     }
   };
 }
-module.exports = { createPlatform, validateConfig };
+module.exports = { createPlatform, validateConfig, runtimeIdentity };

package/lib/transport.js

@@ -1,6 +1,11 @@
 'use strict';
 
 const { UUID, normalise, FanError, check, encodePin, confirmAuth } = require('./protocol');
+const { performance } = require('node:perf_hooks');
+// Side-channel metadata only: preserve the original error and retry semantics.
+// Never copy backend messages, addresses, PINs or characteristic payloads.
+const failures = new WeakMap();
+const failureDetails = error => error && typeof error === 'object' ? failures.get(error) : undefined;
 
 async function bounded(promise, ms, code = 'BLE_TIMEOUT') {
   let timer;
@@ -17,15 +22,17 @@ class Transport {
     this.noble = noble; this.timeout = timeout; this.tail = Promise.resolve();
     this.authSettle = authSettle;
     this.pending = 0; this.closed = false; this.peripheral = null;
+    this.sequence = 0;
   }
   run(mac, pin, action) {
     if (this.closed || this.pending >= 32) return Promise.reject(new FanError('BLE_UNAVAILABLE'));
+    const queued = performance.now(), attempt = ++this.sequence;
     this.pending++;
-    const job = this.tail.then(() => this.session(mac, pin, action));
+    const job = this.tail.then(() => this.session(mac, pin, action, { queued, attempt }));
     this.tail = job.catch(() => {}).finally(() => { this.pending--; });
     return job;
   }
-  async find(mac) {
+  async find(mac, step = (_stage, action) => action()) {
     check(this.noble.state === 'poweredOn', 'BLUETOOTH_NOT_READY');
     return new Promise((resolve, reject) => {
       let settled = false;
@@ -33,7 +40,7 @@ class Transport {
         clearTimeout(timer); this.noble.removeListener('discover', found);
         this.noble.removeListener('stateChange', changed);
         if (this.noble.stopScanningAsync) {
-          await bounded(this.noble.stopScanningAsync(), this.timeout, 'SCAN_STOP_FAILED');
+          await step('scan-stop', () => bounded(this.noble.stopScanningAsync(), this.timeout, 'SCAN_STOP_FAILED'));
         } else { this.noble.stopScanning(); }
       };
       const fail = code => {
@@ -52,32 +59,56 @@ class Transport {
       catch (_) { fail('SCAN_FAILED'); }
     });
   }
-  async session(mac, pin, action) {
-    check(!this.closed, 'BLE_UNAVAILABLE');
-    // Retry a stalled disconnect before reusing the radio. Never overlap an
-    // unresolved connection or pretend the backend has disconnected.
-    check(!this.connecting, 'BLE_RECOVERY_REQUIRED');
+  async session(mac, pin, action, context = { queued: performance.now(), attempt: 0 }) {
+    const started = performance.now(), queueMs = Math.round(started - context.queued);
+    let completed = 'none';
+    const observed = new WeakSet();
+    const step = async (stage, operation) => {
+      const at = performance.now();
+      try {
+        const result = await operation();
+        completed = stage;
+        return result;
+      } catch (error) {
+        if (error && typeof error === 'object' && !observed.has(error)) {
+          observed.add(error);
+          failures.set(error, Object.freeze({ attempt: context.attempt, stage, completed, queueMs,
+            stageMs: Math.round(performance.now() - at), sessionMs: Math.round(performance.now() - started) }));
+        }
+        throw error;
+      }
+    };
+    await step('preflight', () => {
+      check(!this.closed, 'BLE_UNAVAILABLE');
+      // Retry a stalled disconnect before reusing the radio. Never overlap an
+      // unresolved connection or pretend the backend has disconnected.
+      check(!this.connecting, 'BLE_RECOVERY_REQUIRED');
+    });
     if (this.peripheral && this.peripheral.state !== 'disconnected') {
-      try { await bounded(this.peripheral.disconnectAsync(), this.timeout, 'BLE_RECOVERY_REQUIRED'); }
-      catch (_) { throw new FanError('BLE_RECOVERY_REQUIRED'); }
-      check(this.peripheral.state === 'disconnected', 'BLE_RECOVERY_REQUIRED');
+      await step('recover-disconnect', async () => {
+        try { await bounded(this.peripheral.disconnectAsync(), this.timeout, 'BLE_RECOVERY_REQUIRED'); }
+        catch (_) { throw new FanError('BLE_RECOVERY_REQUIRED'); }
+        check(this.peripheral.state === 'disconnected', 'BLE_RECOVERY_REQUIRED');
+      });
     }
-    const peripheral = await this.find(mac);
+    const peripheral = await step('scan', () => this.find(mac, step));
     this.peripheral = peripheral;
     let expired = false;
     try {
-      this.connecting = true;
-      const connection = peripheral.connectAsync();
-      // Noble may complete a connection after its timeout. Disconnect it then.
-      connection.then(() => {
-        this.connecting = false;
-        if (expired || this.closed) { try { peripheral.disconnect(() => {}); } catch (_) { /* recovery gate remains */ } }
-      }, () => { this.connecting = false; });
-      await bounded(connection, this.timeout);
-      check(!this.closed, 'BLE_UNAVAILABLE');
+      await step('connect', async () => {
+        this.connecting = true;
+        const connection = peripheral.connectAsync();
+        // Noble may complete a connection after its timeout. Disconnect it then.
+        connection.then(() => {
+          this.connecting = false;
+          if (expired || this.closed) { try { peripheral.disconnect(() => {}); } catch (_) { /* recovery gate remains */ } }
+        }, () => { this.connecting = false; });
+        await bounded(connection, this.timeout);
+        check(!this.closed, 'BLE_UNAVAILABLE');
+      });
       const chars = new Map();
-      for (const service of await bounded(peripheral.discoverServicesAsync(), this.timeout)) {
-        for (const char of await bounded(service.discoverCharacteristicsAsync(), this.timeout)) chars.set(normalise(char.uuid), char);
+      for (const service of await step('discover-services', () => bounded(peripheral.discoverServicesAsync(), this.timeout))) {
+        for (const char of await step('discover-characteristics', () => bounded(service.discoverCharacteristicsAsync(), this.timeout))) chars.set(normalise(char.uuid), char);
       }
       const get = (name, property) => {
         check(!this.closed, 'BLE_UNAVAILABLE');
@@ -85,19 +116,21 @@ class Transport {
         check(char && char.properties.includes(property), 'CHARACTERISTIC_UNAVAILABLE');
         return char;
       };
-      const read = name => bounded(get(name, 'read').readAsync(), this.timeout);
-      const write = (name, value) => {
+      const label = name => Object.hasOwn(UUID, name) ? name : 'unknown';
+      const read = name => step('read-' + label(name), () => bounded(get(name, 'read').readAsync(), this.timeout));
+      const write = (name, value) => step('write-' + label(name), () => {
         check(['auth', 'manual', 'silent'].includes(name), 'WRITE_NOT_ALLOWED');
         return bounded(get(name, 'write').writeAsync(value, false), this.timeout);
-      };
+      });
       const secret = encodePin(pin);
       try { await write('auth', secret); } finally { secret.fill(0); }
-      confirmAuth(await read('confirmation'));
+      const confirmation = await read('confirmation');
+      await step('authenticate', () => confirmAuth(confirmation));
       // Svara firmware needs a short processing interval after authentication
       // before accepting protected control writes.
-      if (this.authSettle) await new Promise(resolve => setTimeout(resolve, this.authSettle));
+      if (this.authSettle) await step('auth-settle', () => new Promise(resolve => setTimeout(resolve, this.authSettle)));
       check(!this.closed, 'BLE_UNAVAILABLE');
-      return await action({ read, write });
+      return await step('action', () => action({ read, write }));
     } finally {
       expired = true;
       // Noble sets state to disconnecting even when already disconnected;
@@ -116,4 +149,4 @@ class Transport {
     }
   }
 }
-module.exports = { Transport, bounded };
+module.exports = { Transport, bounded, failureDetails };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "homebridge-pax-calima",
   "displayName": "SvaraHome",
-  "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.",
+  "version": "2.6.0-beta.2",
+  "description": "SvaraHome brings CO₂ Clear automation, timed Boost, Pause and local Bluetooth fan control into Apple Home.",
   "main": "index.js",
   "keywords": [
     "homebridge-plugin",
@@ -16,7 +16,9 @@
     "extractor",
     "bathroom",
     "supports-hap",
-    "svarahome"
+    "svarahome",
+    "co2",
+    "ventilation"
   ],
   "engines": {
     "homebridge": "^1.8.0 || ^2.0.0",
@@ -33,7 +35,7 @@
   "license": "Apache-2.0",
   "scripts": {
     "test": "node --test test/*.test.js",
-    "check": "node --check index.js && node --check lib/accessory.js && node --check lib/platform.js && node --check lib/protocol.js && node --check lib/transport.js",
+    "check": "node --check index.js && node --check lib/accessory.js && node --check lib/platform.js && node --check lib/protocol.js && node --check lib/transport.js && node --check lib/co2-clear.js",
     "audit:release": "npm audit --audit-level=high && npm audit --omit=dev --audit-level=high",
     "check:native": "node scripts/check-native.cjs"
   },
@@ -57,7 +59,8 @@
     "scripts/check-native.cjs",
     "docs/BETA1-LIVE-DIAGNOSTIC.md",
     "docs/pi-live-control-evidence-20261025.jsonl",
-    "docs/STABLE-PROMOTION.md"
+    "docs/STABLE-PROMOTION.md",
+    "docs/CO2-CLEAR-BETA.md"
   ],
   "dependencies": {
     "@stoprocent/noble": "2.8.0"