npm - homebridge-pax-calima - Versions diffs - 2.3.2 → 2.4.1 - Mend

homebridge-pax-calima 2.3.2 → 2.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -2,7 +2,13 @@
 **Homebridge 2.0 Ready** · [npm](https://www.npmjs.com/package/homebridge-pax-calima) · [GitHub](https://github.com/JayC68/homebridge-pax-calima)
-Full HomeKit integration for **Pax Calima** (Scandinavia) and **Vent-Axia Svara** (UK) Bluetooth LE bathroom extractor fans. These are hardware-identical and use the exact same BLE protocol and MAC prefix (`58:2b:db`).
+Full HomeKit integration for **Pax Calima** and **Vent-Axia Lo-Carbon Svara** Bluetooth LE bathroom extractor fans.
+**Compatible devices:**
+- **Pax Calima** — Sweden, Norway, Denmark, Finland, Spain, Portugal
+- **Vent-Axia Lo-Carbon Svara** White & Black — UK
+All are hardware-identical, sharing the same BLE protocol and MAC prefix (`58:2b:db`).
 ---
@@ -10,38 +16,49 @@ Full HomeKit integration for **Pax Calima** (Scandinavia) and **Vent-Axia Svara*
 | Feature | Detail |
 |---|---|
-| **Auto-discovery** | Finds all Pax/Svara fans automatically — no MAC address needed |
-| **Fan speed indicator** | Displays current RPM as 0–100% in Apple Home |
-| **Fan speed control** | Speed slider available — see wiring note below |
+| **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 readings in lux, updates every 10 seconds |
-| **Boost button** | Stateless programmable switch — triggers temporary high-speed boost |
-| **Silent Hours** | Toggle switch — prevents fan boosting during scheduled quiet periods |
-| **Automations** | Full support — trigger on humidity, temperature or light thresholds |
+| **Light sensor** | Live lux readings, updates every 10 seconds |
+| **Boost button** | Stateless programmable switch |
+| **Silent Hours** | Toggle — suppresses automatic boosting during quiet periods |
+| **Automations** | Full HomeKit automation support on all sensors |
 ---
 ## Requirements
 - Homebridge `^1.6.0` or `^2.0.0`
-- Node.js `>= 18`
-- A Bluetooth LE adapter on the Homebridge host (built-in or USB dongle)
+- Node.js `>= 18.20.4`
+- A Bluetooth LE adapter on the Homebridge host
+### Homebridge 2.0 Compliance
-### Raspberry Pi / Homebridge OS setup
+This plugin is fully compliant with Homebridge 2.0:
+- Implemented as a **dynamic platform** (`registerPlatform` with `true` flag)
+- Waits for `didFinishLaunching` before any BLE or accessory operations
+- All errors caught and logged — no unhandled exceptions
+- No analytics, no tracking, no post-install scripts
+- Accessories restored from cache without re-registration
+- Compatible with Node.js 18, 20 and 22
-The `noble` BLE library requires elevated network capabilities. Run **once** after installation:
+### Raspberry Pi / Homebridge OS — one-time setup
+The `noble` BLE library requires elevated network capabilities. Run **once** after installation on the **Homebridge terminal**:
 ```bash
 sudo setcap cap_net_raw+eip /opt/homebridge/bin/node
 ```
-If Bluetooth shows as `poweredOff` after this, unblock the radio:
+If Bluetooth shows as `poweredOff`:
 ```bash
 sudo rfkill unblock bluetooth
 ```
+If the above does not resolve the issue, a full Pi power cycle may be required to reinitialise the BLE stack cleanly.
 ---
 ## Installation
@@ -58,9 +75,7 @@ npm install -g homebridge-pax-calima
 ## Configuration
-Auto-discovery requires **no configuration**. The plugin finds any fan with MAC address starting `58:2b:db` automatically and registers it with a default name.
-To set a **custom name** or **PIN** for a specific fan, add an entry to the `fans` array:
+Auto-discovery requires **no configuration**. To set a custom name or PIN per fan:
 ```json
 {
@@ -76,93 +91,84 @@ To set a **custom name** or **PIN** for a specific fan, add an entry to the `fan
 }
 ```
-The `fans` array is entirely optional. Omit it to use auto-discovery with default names and PIN `012345`.
+The `fans` array is optional. Default PIN is `012345`.
 ---
 ## Accessories in Apple Home
-Each discovered fan appears in the Home app as a single accessory with the following tiles:
+Each fan appears as a single accessory with:
-- **Fan** — displays current speed; slider available (see wiring note below)
-- **Boost** — programmable button for temporary high-speed boost
-- **Silent Hours** — switch to suppress automatic boosting during quiet periods
-- **Humidity** — current relative humidity (%)
-- **Temperature** — current temperature (°C)
-- **Light** — current ambient light level (lux)
+- **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
-> Note: Accessories appear in the **Home app**, not in the Homebridge UI accessories tab. This is correct behaviour for child bridge plugins.
+> Accessories appear in the **Home app**, not the Homebridge UI accessories tab. This is correct behaviour for child bridge plugins.
 ---
-## Fan Speed Control — Wiring Mode Note
+## Fan Speed Control — Wiring Mode
-The Pax Calima and Vent-Axia Svara support two wiring modes, selected at installation time:
+The fan supports two installation wiring modes selected at installation time:
-**Intermittent mode** — the fan is off by default and triggered by humidity, light, or a timer. In this mode BLE speed commands are fully respected and the speed slider in Apple Home controls the fan directly.
+**Intermittent mode** — fan is off by default, triggered by sensors or timer. BLE speed commands are fully respected and the slider controls the fan directly.
-**Always-on (trickle) mode** — the fan runs continuously at a speed determined by its onboard controller, typically set via the official app or physical dial. In this mode BLE speed writes are accepted by the fan but the onboard firmware immediately reasserts its own speed. The slider will appear to have no effect.
+**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 speed setpoint immediately. The slider accurately reflects current RPM but cannot override the onboard speed.
-If your fan is wired in always-on mode, the speed slider will reflect the current RPM accurately but cannot override the onboard setpoint. The sensors and automations remain fully functional regardless of wiring mode — for bathroom and wetroom use this is the primary value of the integration, enabling powerful Apple Home automations based on live humidity, temperature and light readings.
+In always-on mode, the sensors and automations remain fully functional and represent the primary value of the integration — particularly for bathroom and wetroom use where humidity, temperature and light thresholds enable powerful Apple Home automations.
-To enable full speed control, consult your fan's installation guide to switch to intermittent wiring mode.
+To enable full speed control, switch to intermittent wiring mode per the fan's installation guide.
 ---
 ## Sensor Notes
-The Svara's light sensor detects occupancy via light movement and shadows rather than acting as a calibrated lux meter. Readings may vary slightly from a reference device depending on mounting position — this is expected.
+Humidity and light values are guaranteed fresh on every poll — the plugin uses a connect→read→disconnect cycle which forces the device's GATT server to return live readings rather than cached values.
-Humidity and temperature automations work well natively in the Home app. For lux-based automations, use a third-party app such as **Eve** or **Hesperus** which support lux thresholds and sync back to HomeKit.
+The light sensor detects occupancy via movement and shadow rather than acting as a precision lux meter. Small variances from a handheld reference device are normal and expected, particularly with ceiling or wall mounting angles.
+For lux-based automations use **Eve** or **Hesperus**, which support lux thresholds synced back to HomeKit.
 ---
 ## Troubleshooting
-**Fan not discovered**
-- Confirm BLE is active: run `hciconfig` on the Pi — look for `UP RUNNING`
-- If it shows `RF-KILL`: run `sudo rfkill unblock bluetooth`
-- Confirm `setcap` targets the correct Node binary: `/opt/homebridge/bin/node`
+**Fan not discovered** — run `hciconfig` on the Pi; confirm `UP RUNNING`. If showing `RF-KILL` run `sudo rfkill unblock bluetooth`. If still not found, perform a full Pi power cycle to reinitialise the BLE stack.
-**Authentication failed**
-- Default PIN is `012345`. If you set a custom PIN in the official Pax/Svara app, add the fan to the `fans` config array with the correct PIN.
+**Authentication failed** — default PIN is `012345`. If changed in the official app, add the fan to the `fans` config array with the correct PIN.
-**Speed slider has no effect**
-- Your fan is likely wired in always-on mode. See the wiring note above. All sensors and automations are unaffected.
+**Speed slider has no effect** — fan is wired in always-on mode. See wiring note above. All sensors work normally.
-**Accessories not appearing in Home app**
-- Remove the accessory cache via Homebridge UI → (plugin settings) → Remove Accessory Cache, then restart Homebridge
+**Accessories not in Home app** — clear accessory cache via Homebridge UI → plugin settings → Remove Accessory Cache, then restart.
 ---
 ## Release Notes
+### 2.4.1
+- **Fixed:** Humidity and light sensors returning stale values — root cause identified as the device's GATT server only refreshing sensor values on a new connection. Poll cycle reverted to proven connect→auth→read→disconnect pattern which guarantees live readings on every poll
+- **Fixed:** Characteristics discovered and cached once per poll cycle — eliminates the intermittent `Characteristic not found` errors seen in 2.4.0
+- **Fixed:** Overlapping poll guard prevents concurrent BLE connections
+- **Improved:** `writeSpeed` correctly skips if a poll is in progress to avoid BLE conflicts
+- **Improved:** Node.js minimum version updated to `18.20.4` per Homebridge 2.0 specification
+- **Documented:** Homebridge 2.0 compliance details added to README
+### 2.4.0
+- **Rebuilt:** Persistent connection architecture — connect once, cache characteristics, poll with direct reads. Fast RPM and temperature updates confirmed. Humidity and light subsequently found to return stale GATT cached values on persistent connections — resolved in 2.4.1
 ### 2.3.2
-- **Documented:** Fan speed control behaviour in always-on vs intermittent wiring modes — the slider correctly reflects current RPM in both modes; in always-on mode the onboard firmware reasserts its own speed setpoint after each BLE write
-- **Confirmed:** All sensors (humidity, temperature, light, RPM) accurate and stable
-- **Improved:** README wiring mode explanation, troubleshooting entry for speed slider, sensor automation guidance
+- Documented always-on vs intermittent wiring mode behaviour
 ### 2.3.1
-- **Investigated:** Correct control characteristic identified (`1488a757...`) via live BLE dump
-- **Added:** Diagnostic logging of control characteristic on every poll and before/after writes
-- **Fixed:** `writeSpeed` pauses poll cycle to avoid BLE conflicts during writes
-### 2.3.0
-- **Published:** Stable sensor readings verified against real-world reference device
-- **Fixed:** Auth characteristic discovery on first connection after restart
+- Identified correct control characteristic; write diagnostics added
-### 2.2.1
-- **Fixed:** Sensors no longer stuck after restart — polling deferred until BLE is ready
-- **Fixed:** Poll interval 30s → 10s for responsive shower humidity tracking
-- **Fixed:** Overlapping poll guard prevents concurrent BLE connections
-- **Fixed:** Multi Mode and Heat Distribution switches removed — not applicable for UK use
-- **Fixed:** Duplicate accessory registration on restart resolved
-- **Fixed:** Switch UUID collision resolved with explicit subtypes
-### 2.1.0
-- **Fixed:** Correct sensor characteristic UUIDs and byte mappings confirmed via live device
-- **Fixed:** BLE refactored to connect → auth → read → disconnect → repeat pattern
-- **Fixed:** UUID matching on Linux noble
+### 2.3.0 / 2.2.1 / 2.1.0
+- Sensor UUIDs and byte mappings confirmed via live device dump
+- BLE initialisation fixes for Homebridge 2.0
+- Duplicate accessory registration resolved
 ### 1.0.x
 - Initial working releases

package/config.schema.json CHANGED Viewed

@@ -11,22 +11,58 @@
         "default": "Pax Calima / Vent-Axia Svara"
       },
       "fans": {
-        "title": "Configured 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.",
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
-            "name": { "title": "Name", "type": "string", "default": "Bathroom Fan" },
+            "name": {
+              "title": "Accessory Name",
+              "type": "string",
+              "default": "Bathroom Fan"
+            },
             "mac": {
               "title": "MAC Address",
               "type": "string",
-              "pattern": "^([0-9A-Fa-f]{2}[:]){5}([0-9A-Fa-f]{2})$",
-              "placeholder": "e.g. 58:2b:db:00:00:00"
+              "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."
             },
-            "pin": { "title": "PIN Code", "type": "string", "default": "012345" }
-          }
+            "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."
+            }
+          },
+          "required": ["name", "mac"]
         }
       }
     }
-  }
+  },
+  "layout": [
+    {
+      "type": "section",
+      "title": "General",
+      "expandable": false,
+      "items": ["name"]
+    },
+    {
+      "type": "section",
+      "title": "Fans (optional — auto-discovery recommended)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        {
+          "key": "fans",
+          "type": "array",
+          "items": [
+            "fans[].name",
+            "fans[].mac",
+            "fans[].pin"
+          ]
+        }
+      ]
+    }
+  ]
 }

package/index.js CHANGED Viewed

@@ -1,15 +1,18 @@
+'use strict';
 const noble = require('@abandonware/noble');
 let Service, Characteristic, Categories, API, PlatformAccessory;
-const UUID_AUTH    = '4cad343a-209a-40b7-b911-4d9b3df569b2';
-const UUID_STATUS  = '528b80e8-c47a-4c0a-bdf1-916a7748f412'; // read: RPM + temp
-const UUID_SENSOR  = 'a22eae12-dba8-49f3-9c69-1721dcff1d96'; // read: humidity + lux
-const UUID_CONTROL = '1488a757-35bc-4ec8-9a6b-9ecf1502778e'; // read/write: speed config
+// ── 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] as UInt16LE pairs
-const MAC_PREFIX      = '58:2b:db';
-const POLL_MS         = 10000;
-const SCAN_TIMEOUT_MS = 15000;
+const MAC_PREFIX   = '58:2b:db';
+const POLL_MS      = 10000;  // 10s — responsive for shower humidity spikes
+const RECONNECT_MS = 15000;
 module.exports = (homebridge) => {
   Service           = homebridge.hap.Service;
@@ -17,9 +20,12 @@ module.exports = (homebridge) => {
   Categories        = homebridge.hap.Categories;
   API               = homebridge;
   PlatformAccessory = homebridge.platformAccessory;
+  // 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;
@@ -27,23 +33,26 @@ class PaxCalimaPlatform {
     this.api               = api;
     this.registeredMACs    = new Set();
     this.discoveryStarted  = false;
-    this.cachedAccessories = [];
+    this.cachedAccessories = []; // held until BLE is ready after didFinishLaunching
     this.log.info('PaxCalima platform initialised');
     this.api.on('didFinishLaunching', () => {
-      this.log.info('Homebridge finished launching - starting BLE');
+      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(() => {
-        this.log.info('BLE current state: ' + noble.state);
         if (noble.state === 'poweredOn') this.startDiscovery();
       }, 3000);
     });
   }
+  // Called by Homebridge for each cached accessory on startup.
+  // Held until startDiscovery() confirms BLE is ready — prevents polling
+  // before the BLE stack is initialised.
   configureAccessory(accessory) {
     const mac = accessory.context && accessory.context.mac;
     this.log.info('Restoring cached accessory: ' + accessory.displayName);
@@ -57,13 +66,14 @@ class PaxCalimaPlatform {
     if (this.discoveryStarted) return;
     this.discoveryStarted = true;
+    // Spin up BLE handlers for all previously registered accessories
     for (const { accessory, mac } of this.cachedAccessories) {
-      const pin = this.pinForMac(mac);
-      this.log.info('Starting BLE handler for cached fan: ' + mac);
-      new PaxCalimaAccessory(this.log, accessory, mac, pin);
+      this.log.info('Starting handler for cached fan: ' + mac);
+      new PaxCalimaAccessory(this.log, accessory, mac, this.pinForMac(mac));
     }
     this.cachedAccessories = [];
+    // Scan for any new fans not yet registered
     this.log.info('Starting BLE discovery scan...');
     noble.startScanning([], false);
@@ -71,23 +81,25 @@ class PaxCalimaPlatform {
       const mac = peripheral.address.toLowerCase();
       if (!mac.startsWith(MAC_PREFIX)) return;
       if (this.registeredMACs.has(mac)) return;
       this.registeredMACs.add(mac);
       this.log.info('Discovered new fan: ' + mac);
-      const name  = this.nameForMac(mac);
-      const pin   = this.pinForMac(mac);
-      const uuid  = API.hap.uuid.generate('pax-svara-' + mac);
-      const hbAcc = new PlatformAccessory(name, uuid, Categories.FAN);
+      const uuid  = API.hap.uuid.generate('pax-calima-' + mac);
+      const hbAcc = new PlatformAccessory(this.nameForMac(mac), uuid, Categories.FAN);
       hbAcc.context.mac = mac;
-      new PaxCalimaAccessory(this.log, hbAcc, mac, pin);
+      new PaxCalimaAccessory(this.log, hbAcc, mac, this.pinForMac(mac));
       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 || ('Vent-Axia Svara ' + mac.slice(-5).toUpperCase()); }
+  nameForMac(mac) { return this.fanConfig(mac).name || ('Pax Calima ' + mac.slice(-5).toUpperCase()); }
 }
+// ─── Accessory ────────────────────────────────────────────────────────────────
 class PaxCalimaAccessory {
   constructor(log, accessory, mac, pin) {
     this.log       = log;
@@ -95,6 +107,7 @@ class PaxCalimaAccessory {
     this.mac       = mac.toLowerCase();
     this.pin       = pin || '012345';
+    // Sensor state — served to HomeKit between polls
     this.currentRPM  = 0;
     this.humidity    = 0;
     this.temperature = 20;
@@ -102,15 +115,17 @@ class PaxCalimaAccessory {
     this.silentHours = false;
     this.pollTimer = null;
-    this.polling   = false;
+    this.polling   = false; // guard against overlapping cycles
     this.setupServices();
-    this.schedulePoll(0);
+    this.schedulePoll(0); // BLE is ready by the time constructor is called
   }
+  // ── HomeKit services ────────────────────────────────────────────────────────
   setupServices() {
     const n = this.accessory.displayName;
+    // 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)
@@ -120,17 +135,20 @@ class PaxCalimaAccessory {
       .onGet(() => this.rpmToPercent(this.currentRPM))
       .onSet((v) => this.writeSpeed(v));
+    // Boost — stateless single-press button
     this.boostButton = this.accessory.getService(Service.StatelessProgrammableSwitch)
       || this.accessory.addService(new Service.StatelessProgrammableSwitch(n + ' Boost', 'boost'));
     this.boostButton.getCharacteristic(Characteristic.ProgrammableSwitchEvent)
       .setProps({ validValues: [0] });
+    // Silent Hours — suppresses automatic boosting during quiet periods
     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)
@@ -146,9 +164,13 @@ class PaxCalimaAccessory {
     this.lightService.getCharacteristic(Characteristic.CurrentAmbientLightLevel)
       .onGet(() => Math.max(0.0001, this.lightLevel));
-    this.log.info('Services set up for: ' + n);
+    this.log.info('Services ready: ' + n);
   }
+  // ── Poll cycle: connect → auth → read → disconnect → wait → repeat ──────────
+  // The device's GATT server only returns fresh sensor values on a new connection.
+  // A persistent connection returns cached values for humidity and light.
+  // We therefore use short-lived connections — proven reliable in testing.
   schedulePoll(delayMs) {
     if (this.pollTimer) clearTimeout(this.pollTimer);
     this.pollTimer = setTimeout(() => this.poll(), delayMs);
@@ -158,59 +180,69 @@ class PaxCalimaAccessory {
     if (this.polling) { this.schedulePoll(POLL_MS); return; }
     this.polling = true;
     let peripheral = null;
     try {
       peripheral = await this.findPeripheral();
       await peripheral.connectAsync();
-      const authChar = await this.getCharacteristic(peripheral, UUID_AUTH);
+      // 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) charCache[c.uuid.replace(/-/g, '')] = c;
+      }
+      // 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);
-      const statusChar = await this.getCharacteristic(peripheral, UUID_STATUS);
+      // Read status: RPM + temperature
+      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;
-      const sensorChar = await this.getCharacteristic(peripheral, UUID_SENSOR);
+      // Read sensors: humidity + lux — fresh values guaranteed on each new connection
+      const sensorChar = charCache[UUID_SENSOR.replace(/-/g, '')];
+      if (!sensorChar) throw new Error('Sensor characteristic not found');
       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));
-      // Also log the raw control characteristic on each poll for diagnostics
-      try {
-        const ctrlChar = await this.getCharacteristic(peripheral, UUID_CONTROL);
-        const ctrlData = await ctrlChar.readAsync();
-        this.log.info('CTRL raw: ' + Array.from(ctrlData).join(',') +
-          ' | UInt16s: ' + ctrlData.readUInt16LE(0) + ',' +
-          ctrlData.readUInt16LE(2) + ',' + ctrlData.readUInt16LE(4));
-      } catch (_) {}
+      // Push all values to HomeKit
       const speed = this.rpmToPercent(this.currentRPM);
       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('Status: RPM=' + this.currentRPM + ' Speed=' + speed +
+      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);
     } finally {
+      // Always disconnect cleanly — required for fresh sensor reads next cycle
       if (peripheral) { try { await peripheral.disconnectAsync(); } catch (_) {} }
       this.polling = false;
       this.schedulePoll(POLL_MS);
     }
   }
+  // Targeted scan — resolves as soon as our 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));
-      }, SCAN_TIMEOUT_MS);
+      }, 20000);
       const onDiscover = (periph) => {
         if (periph.address.toLowerCase() === this.mac) {
           clearTimeout(timeout);
@@ -218,57 +250,53 @@ class PaxCalimaAccessory {
           resolve(periph);
         }
       };
       noble.on('discover', onDiscover);
       noble.startScanning([], false);
     });
   }
-  async getCharacteristic(peripheral, uuid) {
-    const stripped = uuid.replace(/-/g, '');
-    const services = await peripheral.discoverServicesAsync();
-    for (const service of services) {
-      const chars = await service.discoverCharacteristicsAsync();
-      for (const char of chars) {
-        if (char.uuid.replace(/-/g, '') === stripped) return char;
-      }
-    }
-    throw new Error('Characteristic ' + uuid + ' not found');
-  }
+  // ── Fan speed write ─────────────────────────────────────────────────────────
+  // Note: in always-on wiring mode the fan's onboard controller will reassert
+  // its own speed setpoint after each write. See README for details.
   async writeSpeed(percent) {
-    // Pause the poll cycle to avoid BLE conflicts during a write
-    if (this.pollTimer) { clearTimeout(this.pollTimer); this.pollTimer = null; }
+    if (this.polling) {
+      this.log.warn('Speed write skipped — poll in progress');
+      return;
+    }
     let peripheral = null;
     try {
       peripheral = await this.findPeripheral();
       await peripheral.connectAsync();
-      const authChar = await this.getCharacteristic(peripheral, UUID_AUTH);
+      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);
-      // Read current control config to preserve trickle/boost values
-      const ctrlChar = await this.getCharacteristic(peripheral, UUID_CONTROL);
-      const current  = await ctrlChar.readAsync();
-      this.log.info('CTRL before write: ' + Array.from(current).join(','));
+      const ctrlChar = charCache[UUID_CONTROL.replace(/-/g, '')];
+      if (!ctrlChar) throw new Error('Control characteristic not found');
-      // Control characteristic layout (6 bytes, all UInt16LE):
-      // [0-1] trickle RPM, [2-3] normal RPM, [4-5] boost RPM
-      // We write the target RPM into the normal speed slot [2-3]
+      // Preserve existing trickle + boost values, update normal speed slot only
+      const current   = await ctrlChar.readAsync();
       const targetRPM = Math.round((percent / 100) * 2400);
-      const buf = Buffer.from(current); // preserve existing trickle + boost values
-      buf.writeUInt16LE(targetRPM, 2);  // set normal speed
+      const buf       = Buffer.from(current);
+      buf.writeUInt16LE(targetRPM, 2);
       await ctrlChar.writeAsync(buf, true);
+      this.log.info('Speed set to ' + percent + '% (' + targetRPM + ' RPM)');
-      this.log.info('Speed set to ' + percent + '% (' + targetRPM + ' RPM) — CTRL written: ' + Array.from(buf).join(','));
-    } catch (e) {
-      this.log.error('writeSpeed failed: ' + e.message);
+    } catch (err) {
+      this.log.error('writeSpeed failed: ' + err.message);
     } finally {
       if (peripheral) { try { await peripheral.disconnectAsync(); } catch (_) {} }
-      // Resume polling after write
-      this.schedulePoll(2000);
     }
   }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-pax-calima",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "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"