homebridge-pax-calima 2.4.0 → 2.4.2

package/README.md

@@ -1,58 +1,86 @@
 # homebridge-pax-calima
 
-**Homebridge 2.0 Ready** · [npm](https://www.npmjs.com/package/homebridge-pax-calima) · [GitHub](https://github.com/JayC68/homebridge-pax-calima)
+**Bring your bathroom fan into Apple Home — no hub, no cloud, just Bluetooth.**
 
-Full HomeKit integration for **Pax Calima** and **Vent-Axia Lo-Carbon Svara** Bluetooth LE bathroom extractor fans.
+If you have a **Pax Calima** or **Vent-Axia Lo-Carbon Svara** extractor fan, this plugin connects it directly to HomeKit via Bluetooth. Once installed, your fan shows up in the Home app with live temperature, light level and fan speed — and you can build automations around all of them.
 
-Compatible devices:
-- **Pax Calima** — Sweden, Norway, Denmark, Finland, Spain, Portugal
-- **Vent-Axia Lo-Carbon Svara** (White & Black) — UK
+[![Homebridge 2.0 Ready](https://img.shields.io/badge/Homebridge-2.0%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)
 
-All are hardware-identical and share the same BLE protocol and MAC prefix (`58:2b:db`).
+---
+
+## Is this the right plugin for your fan?
+
+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 good to go.
+
+**Confirmed compatible:**
+- Pax Calima — sold across Scandinavia and Iberia (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.
 
 ---
 
-## Features
+## What you get in the Home app
+
+Once set up, your fan appears as a single accessory with these tiles:
+
+- 🌡️ **Temperature** — live reading, updates every 10 seconds
+- 💡 **Light level** — lux reading, useful for occupancy automations
+- 💨 **Fan speed** — shows current RPM as a percentage
+- ⚡ **Boost** — a button that triggers the fan's high-speed boost mode
+- 🌙 **Silent Hours** — a switch that tells the fan not to boost overnight
+- 💧 **Humidity** — available but off by default (read the note below before enabling)
 
-| Feature | Detail |
-|---|---|
-| **Auto-discovery** | Finds all compatible fans automatically — no MAC address needed |
-| **Fan speed** | Displays live RPM as 0–100%; speed control available (see wiring note) |
-| **Humidity sensor** | Live readings, updates every 10 seconds |
-| **Temperature sensor** | Live readings, updates every 10 seconds |
-| **Light sensor** | Live lux readings, updates every 10 seconds |
-| **Boost button** | Stateless programmable switch |
-| **Silent Hours** | Toggle switch — suppresses automatic boosting during quiet periods |
-| **Automations** | Full HomeKit automation support on all sensors |
+> Your accessories will appear in the **Home app on your iPhone**, not in the Homebridge UI accessories tab — that's normal for child bridge plugins.
 
 ---
 
-## Requirements
+## A note on humidity
 
+The humidity tile is **turned off by default**, and for good reason.
+
+The fan's Bluetooth firmware doesn't expose humidity as a continuous live reading — it reflects the fan's own internal threshold state and updates infrequently. During our testing, the fan's Bluetooth reported 50% while a calibrated sensor in the same room read 89% after a shower. This isn't a bug in the plugin — it's how the fan's firmware works, and the Home Assistant community has observed the same behaviour.
+
+**If you turn humidity on**, be aware that:
+- Asking Siri "what's the humidity in the bathroom?" may return a stale number
+- Humidity-triggered automations won't fire reliably during a shower
+
+**What does work well for shower detection:** when the fan's internal sensor detects a sharp humidity rise, it boosts to near full speed automatically. A `Fan Speed > 75%` automation in Apple Home is a reliable, practical trigger for "someone's in the shower."
+
+If you still want to enable humidity — perhaps for settled ambient readings rather than real-time monitoring — you can turn it on in the plugin settings with `showHumidity: true`.
+
+---
+
+## Before you start
+
+You'll need:
 - Homebridge `^1.6.0` or `^2.0.0`
-- Node.js `>= 18`
-- A Bluetooth LE adapter on the Homebridge host
+- Node.js `18.20.4` or later
+- A Bluetooth adapter on your Homebridge host (the Raspberry Pi 4's built-in adapter works well)
 
-### Raspberry Pi / Homebridge OS — one-time setup
+**If you're running Homebridge OS on a Raspberry Pi**, there's one extra step after installation. The Bluetooth library needs a small permissions tweak — run this once in the **Homebridge terminal**:
 
 ```bash
 sudo setcap cap_net_raw+eip /opt/homebridge/bin/node
 ```
 
-If Bluetooth shows as `poweredOff`:
+If Bluetooth shows as off after that:
 
 ```bash
 sudo rfkill unblock bluetooth
 ```
 
+And if things still aren't working after both of those — a full **power cycle** of the Pi (unplug, wait, replug) tends to sort it. A software restart alone sometimes isn't enough to reinitialise the Bluetooth stack cleanly.
+
 ---
 
 ## Installation
 
-### Via Homebridge UI (recommended)
-Search for **Pax Calima** or **Svara** and click Install.
+Search for **Pax Calima** or **Svara** in the Homebridge UI and click Install — that's it.
 
-### Via Terminal
+Or via terminal:
 ```bash
 npm install -g homebridge-pax-calima
 ```
@@ -61,12 +89,15 @@ npm install -g homebridge-pax-calima
 
 ## Configuration
 
-No configuration needed for auto-discovery. To set a custom name or PIN per fan:
+**You don't need to configure anything.** The plugin finds your fan automatically by scanning for Bluetooth devices with the right MAC prefix and registers it in HomeKit.
+
+If you want to give your fan a custom name, or if you've set a non-default PIN in the official app, you can specify those in settings:
 
 ```json
 {
   "platform": "PaxCalima",
   "name": "Pax Calima / Vent-Axia Svara",
+  "showHumidity": false,
   "fans": [
     {
       "name": "Wetroom Fan",
@@ -77,79 +108,85 @@ No configuration needed for auto-discovery. To set a custom name or PIN per fan:
 }
 ```
 
-The `fans` array is optional. Default PIN is `012345`.
+| Setting | Default | What it does |
+|---|---|---|
+| `showHumidity` | `false` | Enables the humidity tile — read the note above first |
+| `fans[].name` | Auto-generated | Sets a friendly name for a specific fan |
+| `fans[].mac` | — | Only needed if you want to assign a name or custom PIN |
+| `fans[].pin` | `012345` | The 6-digit PIN — only change if you set a custom one in the official app |
 
 ---
 
-## Accessories in Apple Home
+## Fan speed control — it depends on how your fan is wired
 
-Each fan appears as a single accessory with:
+The Svara and Calima can be installed in two different modes, and which one you have affects what the speed slider does:
 
-- **Fan** — live speed display; slider available (see wiring note)
-- **Boost** — single-press programmable button
-- **Silent Hours** — on/off switch
-- **Humidity** — % relative humidity
-- **Temperature** — °C
-- **Light** — lux
+**Intermittent mode** — the fan is off by default and spins up when it detects humidity, light, or a timer trigger. In this mode, the speed slider in Apple Home controls the fan directly.
 
-> Accessories appear in the **Home app**, not the Homebridge UI accessories tab. This is correct for child bridge plugins.
+**Always-on (trickle) mode** — the fan runs continuously at a speed managed by its own onboard controller. In this mode, you can send speed commands via Bluetooth and they are accepted — but the fan resets to its own setpoint within seconds. The slider will show you the current speed accurately, but won't be able to change it.
 
----
+If you're not sure which mode you have, check whether your fan is ever fully off. If it's always running (even quietly), you're in always-on mode.
 
-## Fan Speed Control — Wiring Mode
+In either mode, the temperature, light and fan speed automations work perfectly.
 
-The fan supports two installation wiring modes:
+---
 
-**Intermittent mode** — fan is off by default, triggered by sensors or timer. BLE speed commands work fully; the slider controls the fan directly.
+## Something not working?
 
-**Always-on (trickle) mode** — fan runs continuously at a speed set by its onboard controller. BLE speed writes are accepted but the firmware reasserts its own setpoint immediately. The slider accurately reflects current RPM but cannot override the onboard speed.
+**Fan not showing up in Home**
+Try `hciconfig` in the Homebridge terminal — you should see `UP RUNNING` next to `hci0`. If it shows `RF-KILL`, run `sudo rfkill unblock bluetooth`. If still nothing, unplug the Pi, wait 10 seconds, and plug it back in.
 
-If your fan is in always-on mode, sensors and automations remain fully functional — for bathroom and wetroom use these are the primary value of the integration. To enable full speed control, switch to intermittent wiring mode per the installation guide.
+**setcap not sticking / BLE still powered off**
+Make sure you're running setcap against the right binary — on Homebridge OS it's `/opt/homebridge/bin/node`, not whatever `which node` returns.
 
----
+**Wrong PIN / can't authenticate**
+The default PIN is `012345`. If you changed it in the official Pax or Vent-Axia app, add your fan to the `fans` config array with the correct PIN.
 
-## Sensor Notes
+**Speed slider does nothing**
+Your fan is in always-on mode — see the wiring section above. Everything else still works.
 
-The light sensor detects occupancy via movement and shadows rather than acting as a precision lux meter. Small variances from a reference device are expected and normal.
+**Humidity stuck at the same number**
+This is expected — see the humidity note above. If you'd prefer not to see it, set `showHumidity: false` (or just don't enable it in the first place).
 
-For lux-based automations, use **Eve** or **Hesperus** which support lux thresholds synced to HomeKit.
+**Accessories not appearing in the Home app**
+Go to the plugin settings in Homebridge UI, choose Remove Accessory Cache, and restart. They'll re-appear within a few seconds of the plugin starting.
 
 ---
 
-## Troubleshooting
-
-**Fan not discovered** — run `hciconfig` on Pi; confirm `UP RUNNING`. If `RF-KILL`, run `sudo rfkill unblock bluetooth`. Confirm `setcap` was applied to `/opt/homebridge/bin/node`.
+## Homebridge 2.0 compliance
 
-**Authentication failed** — default PIN is `012345`. If changed in the official app, add the fan to the `fans` config with the correct PIN.
+For those who care about the technical details — this plugin meets all Homebridge 2.0 requirements:
+- Registered as a dynamic platform
+- Waits for `didFinishLaunching` before any BLE or accessory work begins
+- All errors are caught and logged — no unhandled exceptions
+- No analytics, no tracking, no post-install scripts
+- Cached accessories restored cleanly without re-registration
+- Compatible with Node.js 18, 20 and 22
 
-**Speed slider has no effect** — fan is wired in always-on mode. See wiring note above. All sensors work normally.
+---
 
-**Accessories not in Home app** — clear accessory cache via Homebridge UI → plugin settings → Remove Accessory Cache, then restart.
+## Release notes
 
----
+### 2.4.2
+- Humidity sensor is now **off by default** — you have to explicitly enable it with `showHumidity: true`. This follows confirmed testing that showed the fan's BLE firmware updates the humidity characteristic infrequently (we measured 50% while a reference sensor read 89% in the same room post-shower). Exposing it by default risked misleading Siri queries and unreliable automations. If you had it enabled previously, it will be removed from your accessory automatically — you can re-enable it knowingly in settings.
+- README rewritten to be more human — less spec sheet, more "here's what to expect and why"
+- Fan speed documented as the practical shower/occupancy trigger
 
-## Release Notes
+### 2.4.1
+- Fixed sensors returning stale values — the device's GATT server only refreshes humidity and light on a new connection, so we now connect → read → disconnect on each poll rather than holding a persistent connection
+- Eliminated intermittent `Characteristic not found` errors
 
 ### 2.4.0
-- **Rebuilt:** Connection architecture reverted to persistent BLE connection model — connect once, cache all characteristics, poll with direct `readAsync()` calls. Eliminates the per-poll scan/connect/auth/discover overhead that made 2.x sluggish and error-prone
-- **Improved:** Both sensor characteristics now read in parallel via `Promise.all` — faster polls
-- **Improved:** Characteristics cached once per connection — no repeated service discovery
-- **Improved:** Auth performed once per connection, not per poll
-- **Improved:** Automatic reconnection on unexpected disconnect with clean cache flush
-- **Fixed:** `Characteristic not found` intermittent errors eliminated — characteristic lookup now uses pre-cached map rather than repeated discovery
-- **Fixed:** `writeSpeed` uses cached control characteristic and preserves trickle/boost values
-- **Fixed:** Default accessory name changed to `Pax Calima` for international compatibility
-
-### 2.3.2
-- Documented always-on vs intermittent wiring mode behaviour for speed control
-
-### 2.3.1
-- Identified correct control characteristic; added write diagnostics
-
-### 2.3.0 / 2.2.1 / 2.1.0
-- Sensor characteristic UUIDs and byte mappings confirmed via live device
-- BLE initialisation fixes for Homebridge 2.0
-- Duplicate accessory registration resolved
+- Rebuilt connection architecture — persistent connection with cached characteristics. Fast and reliable for RPM and temperature; subsequently found that humidity returns stale values on persistent connections (fixed in 2.4.1)
+
+### 2.3.x
+- Identified the correct control characteristic for fan speed writes
+- Documented always-on vs intermittent wiring mode behaviour
+
+### 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 on restart resolved
 
 ### 1.0.x
-- Initial working releases
+- Initial releases

package/config.schema.json

@@ -10,9 +10,15 @@
         "type": "string",
         "default": "Pax Calima / Vent-Axia Svara"
       },
+      "showHumidity": {
+        "title": "Show Humidity Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "⚠️ The fan's humidity characteristic updates infrequently due to a firmware limitation — it reflects the fan's internal settled state, not a real-time reading. It is NOT suitable for use with Siri queries or time-sensitive automations. Only enable this if you understand and accept this limitation. Disabled by default."
+      },
       "fans": {
         "title": "Manually Configured Fans",
-        "description": "Optional. Leave empty to use auto-discovery (recommended). Add entries here only to set a custom name or PIN per fan.",
+        "description": "Optional. Leave empty to use auto-discovery. Add entries here only to set a custom name or PIN per fan.",
         "type": "array",
         "items": {
           "type": "object",
@@ -26,13 +32,13 @@
               "title": "MAC Address",
               "type": "string",
               "pattern": "^([0-9A-Fa-f]{2}:){5}([0-9A-Fa-f]{2})$",
-              "description": "MAC address of the fan (e.g. 58:2b:db:xx:xx:xx). Must start with 58:2b:db."
+              "description": "MAC address of the fan (e.g. 58:2b:db:xx:xx:xx)"
             },
             "pin": {
               "title": "PIN Code",
               "type": "string",
               "default": "012345",
-              "description": "6-digit PIN. Only change this if you set a custom PIN in the official Pax / Vent-Axia app."
+              "description": "6-digit PIN. Only change if you set a custom PIN in the official app."
             }
           },
           "required": ["name", "mac"]
@@ -45,7 +51,7 @@
       "type": "section",
       "title": "General",
       "expandable": false,
-      "items": ["name"]
+      "items": ["name", "showHumidity"]
     },
     {
       "type": "section",

package/index.js

@@ -4,14 +4,14 @@ const noble = require('@abandonware/noble');
 
 let Service, Characteristic, Categories, API, PlatformAccessory;
 
-// ── Verified BLE UUIDs (confirmed via live device dump) ───────────────────────
-const UUID_AUTH    = '4cad343a-209a-40b7-b911-4d9b3df569b2'; // PIN auth — write once
-const UUID_STATUS  = '528b80e8-c47a-4c0a-bdf1-916a7748f412'; // RPM (offset 6) + temp (offset 2)
-const UUID_SENSOR  = 'a22eae12-dba8-49f3-9c69-1721dcff1d96'; // humidity (offset 0) + lux (offset 2 BE)
-const UUID_CONTROL = '1488a757-35bc-4ec8-9a6b-9ecf1502778e'; // speed config — 6 bytes: trickle/normal/boost
+// ── Verified BLE UUIDs (confirmed via live device dump April 2026) ────────────
+const UUID_AUTH    = '4cad343a-209a-40b7-b911-4d9b3df569b2'; // PIN auth — write once per connection
+const UUID_STATUS  = '528b80e8-c47a-4c0a-bdf1-916a7748f412'; // RPM (offset 6 UInt16LE) + temp (offset 2 UInt16LE / 6)
+const UUID_SENSOR  = 'a22eae12-dba8-49f3-9c69-1721dcff1d96'; // humidity (offset 0 UInt8 × 2) + lux (offset 2 UInt16BE)
+const UUID_CONTROL = '1488a757-35bc-4ec8-9a6b-9ecf1502778e'; // speed config: [trickle|normal|boost] UInt16LE pairs
 
 const MAC_PREFIX   = '58:2b:db';
-const POLL_MS      = 10000; // 10s — responsive for shower humidity spikes
+const POLL_MS      = 10000;
 const RECONNECT_MS = 15000;
 
 module.exports = (homebridge) => {
@@ -20,40 +20,33 @@ module.exports = (homebridge) => {
   Categories        = homebridge.hap.Categories;
   API               = homebridge;
   PlatformAccessory = homebridge.platformAccessory;
-
-  // true = dynamic platform, required for Homebridge 2.0
   homebridge.registerPlatform('homebridge-pax-calima', 'PaxCalima', PaxCalimaPlatform, true);
 };
 
 // ─── Platform ─────────────────────────────────────────────────────────────────
 class PaxCalimaPlatform {
   constructor(log, config, api) {
-    this.log              = log;
-    this.config           = config || {};
-    this.api              = api;
-    this.registeredMACs   = new Set();
-    this.discoveryStarted = false;
-    this.cachedAccessories = []; // held until BLE is ready after didFinishLaunching
+    this.log               = log;
+    this.config            = config || {};
+    this.api               = api;
+    this.registeredMACs    = new Set();
+    this.discoveryStarted  = false;
+    this.cachedAccessories = [];
 
     this.log.info('PaxCalima platform initialised');
 
     this.api.on('didFinishLaunching', () => {
       this.log.info('Homebridge finished launching — starting BLE');
-
       noble.on('stateChange', (state) => {
         this.log.info('BLE state: ' + state);
         if (state === 'poweredOn') this.startDiscovery();
       });
-
-      // Catch case where noble is already poweredOn before listener fires
       setTimeout(() => {
         if (noble.state === 'poweredOn') this.startDiscovery();
       }, 3000);
     });
   }
 
-  // Called by Homebridge for each cached accessory on startup.
-  // We hold them until startDiscovery() confirms BLE is ready.
   configureAccessory(accessory) {
     const mac = accessory.context && accessory.context.mac;
     this.log.info('Restoring cached accessory: ' + accessory.displayName);
@@ -67,14 +60,12 @@ class PaxCalimaPlatform {
     if (this.discoveryStarted) return;
     this.discoveryStarted = true;
 
-    // Spin up handlers for all cached (previously registered) accessories
     for (const { accessory, mac } of this.cachedAccessories) {
-      this.log.info('Connecting to cached fan: ' + mac);
-      new PaxCalimaAccessory(this.log, accessory, mac, this.pinForMac(mac));
+      this.log.info('Starting handler for cached fan: ' + mac);
+      new PaxCalimaAccessory(this.log, accessory, mac, this.pinForMac(mac), this.showHumidity());
     }
     this.cachedAccessories = [];
 
-    // Scan for any new fans not yet registered
     this.log.info('Starting BLE discovery scan...');
     noble.startScanning([], false);
 
@@ -90,46 +81,43 @@ class PaxCalimaPlatform {
       const hbAcc = new PlatformAccessory(this.nameForMac(mac), uuid, Categories.FAN);
       hbAcc.context.mac = mac;
 
-      new PaxCalimaAccessory(this.log, hbAcc, mac, this.pinForMac(mac));
+      new PaxCalimaAccessory(this.log, hbAcc, mac, this.pinForMac(mac), this.showHumidity());
       this.api.registerPlatformAccessories('homebridge-pax-calima', 'PaxCalima', [hbAcc]);
     });
   }
 
-  fanConfig(mac)  { return (this.config.fans || []).find(f => f.mac && f.mac.toLowerCase() === mac) || {}; }
-  pinForMac(mac)  { return this.fanConfig(mac).pin  || '012345'; }
-  nameForMac(mac) { return this.fanConfig(mac).name || ('Pax Calima ' + mac.slice(-5).toUpperCase()); }
+  fanConfig(mac)    { return (this.config.fans || []).find(f => f.mac && f.mac.toLowerCase() === mac) || {}; }
+  pinForMac(mac)    { return this.fanConfig(mac).pin  || '012345'; }
+  nameForMac(mac)   { return this.fanConfig(mac).name || ('Pax Calima ' + mac.slice(-5).toUpperCase()); }
+  showHumidity()    { return this.config.showHumidity === true; }
 }
 
 // ─── Accessory ────────────────────────────────────────────────────────────────
 class PaxCalimaAccessory {
-  constructor(log, accessory, mac, pin) {
-    this.log       = log;
-    this.accessory = accessory;
-    this.mac       = mac.toLowerCase();
-    this.pin       = pin || '012345';
+  constructor(log, accessory, mac, pin, showHumidity) {
+    this.log          = log;
+    this.accessory    = accessory;
+    this.mac          = mac.toLowerCase();
+    this.pin          = pin || '012345';
+    this.showHumidity = showHumidity;
 
-    // Sensor state — served to HomeKit between polls
     this.currentRPM  = 0;
     this.humidity    = 0;
     this.temperature = 20;
     this.lightLevel  = 0.0001;
     this.silentHours = false;
 
-    // BLE connection state
-    this.peripheral  = null;
-    this.charCache   = {};   // uuid (stripped) → characteristic — populated once per connection
-    this.connected   = false;
-    this.pollTimer   = null;
+    this.pollTimer = null;
+    this.polling   = false;
 
     this.setupServices();
-    this.connect();          // connect immediately — BLE is ready by the time we're constructed
+    this.schedulePoll(0);
   }
 
-  // ── HomeKit services ────────────────────────────────────────────────────────
   setupServices() {
     const n = this.accessory.displayName;
 
-    // Fan — always reports as active; speed reflects live RPM
+    // Fan — always active; speed reflects live RPM
     this.fanService = this.accessory.getService(Service.Fanv2)
       || this.accessory.addService(new Service.Fanv2(n, 'fan'));
     this.fanService.getCharacteristic(Characteristic.Active)
@@ -145,89 +133,125 @@ class PaxCalimaAccessory {
     this.boostButton.getCharacteristic(Characteristic.ProgrammableSwitchEvent)
       .setProps({ validValues: [0] });
 
-    // Silent Hours — suppresses automatic boosting overnight
+    // Silent Hours
     this.silentService = this.accessory.getServiceByUUIDAndSubType(Service.Switch, 'silent-hours')
       || this.accessory.addService(new Service.Switch(n + ' Silent Hours', 'silent-hours'));
     this.silentService.getCharacteristic(Characteristic.On)
       .onGet(() => this.silentHours)
       .onSet((on) => this.setSilentHours(on));
 
-    // Sensors
-    this.humidityService = this.accessory.getService(Service.HumiditySensor)
-      || this.accessory.addService(new Service.HumiditySensor(n + ' Humidity', 'humidity'));
-    this.humidityService.getCharacteristic(Characteristic.CurrentRelativeHumidity)
-      .onGet(() => this.humidity);
-
+    // Temperature
     this.tempService = this.accessory.getService(Service.TemperatureSensor)
       || this.accessory.addService(new Service.TemperatureSensor(n + ' Temperature', 'temperature'));
     this.tempService.getCharacteristic(Characteristic.CurrentTemperature)
       .onGet(() => this.temperature);
 
+    // Light
     this.lightService = this.accessory.getService(Service.LightSensor)
       || this.accessory.addService(new Service.LightSensor(n + ' Light', 'light'));
     this.lightService.getCharacteristic(Characteristic.CurrentAmbientLightLevel)
       .onGet(() => Math.max(0.0001, this.lightLevel));
 
+    // Humidity — optional, disabled by default due to firmware update frequency limitations
+    // User must explicitly enable via showHumidity: true in config
+    if (this.showHumidity) {
+      this.humidityService = this.accessory.getService(Service.HumiditySensor)
+        || this.accessory.addService(new Service.HumiditySensor(n + ' Humidity', 'humidity'));
+      this.humidityService.getCharacteristic(Characteristic.CurrentRelativeHumidity)
+        .onGet(() => this.humidity);
+      this.log.info('Humidity sensor enabled — note: reflects fan internal settled state, not real-time');
+    } else {
+      // Remove humidity service if it was previously registered and user has since disabled it
+      const existing = this.accessory.getService(Service.HumiditySensor);
+      if (existing) this.accessory.removeService(existing);
+      this.log.info('Humidity sensor disabled (showHumidity not set)');
+    }
+
     this.log.info('Services ready: ' + n);
   }
 
-  // ── BLE connection ──────────────────────────────────────────────────────────
-  async connect() {
-    this.log.info('Connecting to ' + this.mac + '...');
+  schedulePoll(delayMs) {
+    if (this.pollTimer) clearTimeout(this.pollTimer);
+    this.pollTimer = setTimeout(() => this.poll(), delayMs);
+  }
+
+  async poll() {
+    if (this.polling) { this.schedulePoll(POLL_MS); return; }
+    this.polling = true;
+    let peripheral = null;
 
     try {
-      // Find the peripheral via scan
-      this.peripheral = await this.findPeripheral();
-      await this.peripheral.connectAsync();
-      this.log.info('Connected to ' + this.mac);
-
-      // Discover and cache ALL characteristics in one pass
-      this.charCache = {};
-      const services = await this.peripheral.discoverServicesAsync();
+      peripheral = await this.findPeripheral();
+      await peripheral.connectAsync();
+
+      // Discover and cache all characteristics for this connection
+      const charCache = {};
+      const services  = await peripheral.discoverServicesAsync();
       for (const svc of services) {
         const chars = await svc.discoverCharacteristicsAsync();
-        for (const c of chars) {
-          this.charCache[c.uuid.replace(/-/g, '')] = c;
-        }
+        for (const c of chars) charCache[c.uuid.replace(/-/g, '')] = c;
       }
 
-      // Authenticate once — stays valid for the life of this connection
-      const authChar = this.charCache[UUID_AUTH.replace(/-/g, '')];
+      // Authenticate
+      const authChar = charCache[UUID_AUTH.replace(/-/g, '')];
       if (!authChar) throw new Error('Auth characteristic not found');
       const pinBuf = Buffer.alloc(4);
       pinBuf.writeUInt32LE(parseInt(this.pin, 10), 0);
       await authChar.writeAsync(pinBuf, true);
-      this.log.info('Authenticated');
 
-      this.connected = true;
+      // Read status: RPM + temperature — updates live on every connection
+      const statusChar = charCache[UUID_STATUS.replace(/-/g, '')];
+      if (!statusChar) throw new Error('Status characteristic not found');
+      const statusData = await statusChar.readAsync();
+      this.currentRPM  = Math.max(0, statusData.readUInt16LE(6));
+      this.temperature = Math.round((statusData.readUInt16LE(2) / 6) * 10) / 10;
 
-      // Handle unexpected disconnects — reconnect automatically
-      this.peripheral.once('disconnect', () => {
-        this.log.warn(this.mac + ' disconnected — reconnecting in ' + (RECONNECT_MS / 1000) + 's');
-        this.connected = false;
-        this.charCache = {};
-        if (this.pollTimer) { clearTimeout(this.pollTimer); this.pollTimer = null; }
-        setTimeout(() => this.connect(), RECONNECT_MS);
-      });
+      // Read sensor characteristic only if humidity is enabled
+      // The device updates this characteristic infrequently (firmware limitation)
+      if (this.showHumidity) {
+        const sensorChar = charCache[UUID_SENSOR.replace(/-/g, '')];
+        if (sensorChar) {
+          const sensorData = await sensorChar.readAsync();
+          this.humidity   = Math.max(0, Math.min(100, sensorData.readUInt8(0) * 2));
+          this.lightLevel = Math.max(0.0001, sensorData.readUInt16BE(2));
+        }
+      } else {
+        // Read lux from sensor characteristic regardless — only skip humidity update
+        const sensorChar = charCache[UUID_SENSOR.replace(/-/g, '')];
+        if (sensorChar) {
+          const sensorData = await sensorChar.readAsync();
+          this.lightLevel = Math.max(0.0001, sensorData.readUInt16BE(2));
+        }
+      }
+
+      // Push to HomeKit
+      const speed = this.rpmToPercent(this.currentRPM);
+      this.fanService.getCharacteristic(Characteristic.RotationSpeed).updateValue(speed);
+      this.tempService.getCharacteristic(Characteristic.CurrentTemperature).updateValue(this.temperature);
+      this.lightService.getCharacteristic(Characteristic.CurrentAmbientLightLevel).updateValue(this.lightLevel);
+      if (this.showHumidity && this.humidityService) {
+        this.humidityService.getCharacteristic(Characteristic.CurrentRelativeHumidity).updateValue(this.humidity);
+      }
 
-      // Start polling immediately
-      this.poll();
+      this.log.info('Poll: RPM=' + this.currentRPM + ' Speed=' + speed +
+        '% Temp=' + this.temperature + 'C Light=' + this.lightLevel + 'lx' +
+        (this.showHumidity ? ' Hum=' + this.humidity + '%' : ''));
 
     } catch (err) {
-      this.log.error('Connection failed: ' + err.message);
-      this.connected = false;
-      setTimeout(() => this.connect(), RECONNECT_MS);
+      this.log.warn('Poll error: ' + err.message);
+    } finally {
+      if (peripheral) { try { await peripheral.disconnectAsync(); } catch (_) {} }
+      this.polling = false;
+      this.schedulePoll(POLL_MS);
     }
   }
 
-  // Targeted scan — resolves as soon as our specific MAC is seen, removes its own listener
   findPeripheral() {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         noble.removeListener('discover', onDiscover);
         reject(new Error('Scan timeout for ' + this.mac));
       }, 20000);
-
       const onDiscover = (periph) => {
         if (periph.address.toLowerCase() === this.mac) {
           clearTimeout(timeout);
@@ -235,79 +259,40 @@ class PaxCalimaAccessory {
           resolve(periph);
         }
       };
-
       noble.on('discover', onDiscover);
       noble.startScanning([], false);
     });
   }
 
-  // ── Polling — uses cached characteristics, no reconnect overhead ────────────
-  async poll() {
-    if (!this.connected) return;
-
-    try {
-      const statusChar = this.charCache[UUID_STATUS.replace(/-/g, '')];
-      const sensorChar = this.charCache[UUID_SENSOR.replace(/-/g, '')];
-
-      if (!statusChar || !sensorChar) throw new Error('Characteristics not cached — reconnecting');
-
-      // Read both characteristics
-      const [statusData, sensorData] = await Promise.all([
-        statusChar.readAsync(),
-        sensorChar.readAsync(),
-      ]);
-
-      // Parse — confirmed mappings from live device
-      this.currentRPM  = Math.max(0, statusData.readUInt16LE(6));
-      this.temperature = Math.round((statusData.readUInt16LE(2) / 6) * 10) / 10;
-      this.humidity    = Math.max(0, Math.min(100, sensorData.readUInt8(0) * 2));
-      this.lightLevel  = Math.max(0.0001, sensorData.readUInt16BE(2));
-
-      const speed = this.rpmToPercent(this.currentRPM);
-
-      // Push to HomeKit
-      this.fanService.getCharacteristic(Characteristic.RotationSpeed).updateValue(speed);
-      this.humidityService.getCharacteristic(Characteristic.CurrentRelativeHumidity).updateValue(this.humidity);
-      this.tempService.getCharacteristic(Characteristic.CurrentTemperature).updateValue(this.temperature);
-      this.lightService.getCharacteristic(Characteristic.CurrentAmbientLightLevel).updateValue(this.lightLevel);
-
-      this.log.info('Poll: RPM=' + this.currentRPM + ' Speed=' + speed +
-        '% Hum=' + this.humidity + '% Temp=' + this.temperature +
-        'C Light=' + this.lightLevel + 'lx');
-
-    } catch (err) {
-      this.log.warn('Poll error: ' + err.message);
-      // If cache is stale, reconnect
-      if (!this.charCache[UUID_STATUS.replace(/-/g, '')]) {
-        this.connected = false;
-        setTimeout(() => this.connect(), RECONNECT_MS);
-        return;
-      }
-    }
-
-    // Schedule next poll
-    this.pollTimer = setTimeout(() => this.poll(), POLL_MS);
-  }
-
-  // ── Fan speed write ─────────────────────────────────────────────────────────
   async writeSpeed(percent) {
-    if (!this.connected) {
-      this.log.warn('Cannot set speed — not connected');
-      return;
-    }
+    if (this.polling) { this.log.warn('Speed write skipped — poll in progress'); return; }
+    let peripheral = null;
     try {
-      const ctrlChar = this.charCache[UUID_CONTROL.replace(/-/g, '')];
-      if (!ctrlChar) throw new Error('Control characteristic not cached');
-
-      // Read current config to preserve trickle + boost values
-      const current = await ctrlChar.readAsync();
+      peripheral = await this.findPeripheral();
+      await peripheral.connectAsync();
+      const charCache = {};
+      const services  = await peripheral.discoverServicesAsync();
+      for (const svc of services) {
+        const chars = await svc.discoverCharacteristicsAsync();
+        for (const c of chars) charCache[c.uuid.replace(/-/g, '')] = c;
+      }
+      const authChar = charCache[UUID_AUTH.replace(/-/g, '')];
+      if (!authChar) throw new Error('Auth characteristic not found');
+      const pinBuf = Buffer.alloc(4);
+      pinBuf.writeUInt32LE(parseInt(this.pin, 10), 0);
+      await authChar.writeAsync(pinBuf, true);
+      const ctrlChar = charCache[UUID_CONTROL.replace(/-/g, '')];
+      if (!ctrlChar) throw new Error('Control characteristic not found');
+      const current   = await ctrlChar.readAsync();
       const targetRPM = Math.round((percent / 100) * 2400);
-      const buf = Buffer.from(current);
-      buf.writeUInt16LE(targetRPM, 2); // bytes 2-3 = normal speed slot
+      const buf       = Buffer.from(current);
+      buf.writeUInt16LE(targetRPM, 2);
       await ctrlChar.writeAsync(buf, true);
       this.log.info('Speed set to ' + percent + '% (' + targetRPM + ' RPM)');
     } catch (err) {
       this.log.error('writeSpeed failed: ' + err.message);
+    } finally {
+      if (peripheral) { try { await peripheral.disconnectAsync(); } catch (_) {} }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-pax-calima",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Homebridge platform plugin for Pax Calima and Vent-Axia Svara Bluetooth LE bathroom extractor fans",
   "main": "index.js",
   "keywords": [
@@ -17,7 +17,7 @@
   ],
   "engines": {
     "homebridge": "^1.6.0 || ^2.0.0",
-    "node": ">=18.0.0"
+    "node": ">=18.20.4"
   },
   "dependencies": {
     "@abandonware/noble": "1.9.2-26"