homebridge-pax-calima 2.3.1 → 2.3.2

package/README.md

@@ -1,27 +1,168 @@
 # homebridge-pax-calima
 
-Homebridge platform plugin for **Pax Calima** and **Vent-Axia Svara** Bluetooth LE bathroom extractor fans.
+**Homebridge 2.0 Ready** · [npm](https://www.npmjs.com/package/homebridge-pax-calima) · [GitHub](https://github.com/JayC68/homebridge-pax-calima)
 
-The Vent-Axia Svara is the UK rebrand of the Pax Calima — they use the **exact same Bluetooth protocol**, MAC prefix (`58:2b:db`), and GATT characteristics.
+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`).
+
+---
 
 ## Features
-- Automatic discovery of fans (MAC starting with `58:2b:db`)
-- Fan control (On/Off + Rotation Speed 0-100%)
-- Live sensors: Humidity, Temperature, Light level
-- Mode switching (Multi Mode, Heat Distribution)
-- Boost button (press to activate temporary high-speed boost)
-- Silent Hours toggle
-- Automatic cycle switches (30/60/90 min)
-- Trickle ventilation toggle
-- Easy configuration via Homebridge Config UI
-
-Perfect for Apple Home automations.
+
+| 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 |
+| **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 |
+
+---
+
+## 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)
+
+### Raspberry Pi / Homebridge OS setup
+
+The `noble` BLE library requires elevated network capabilities. Run **once** after installation:
+
+```bash
+sudo setcap cap_net_raw+eip /opt/homebridge/bin/node
+```
+
+If Bluetooth shows as `poweredOff` after this, unblock the radio:
+
+```bash
+sudo rfkill unblock bluetooth
+```
+
+---
 
 ## Installation
 
 ### Via Homebridge UI (recommended)
-Search for **Pax Calima** or **Svara** and install.
+Search for **Pax Calima** or **Svara** and click Install.
 
 ### Via Terminal
 ```bash
 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:
+
+```json
+{
+  "platform": "PaxCalima",
+  "name": "Pax Calima / Vent-Axia Svara",
+  "fans": [
+    {
+      "name": "Wetroom Fan",
+      "mac": "58:2b:db:xx:xx:xx",
+      "pin": "012345"
+    }
+  ]
+}
+```
+
+The `fans` array is entirely optional. Omit it to use auto-discovery with default names and PIN `012345`.
+
+---
+
+## Accessories in Apple Home
+
+Each discovered fan appears in the Home app as a single accessory with the following tiles:
+
+- **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)
+
+> Note: Accessories appear in the **Home app**, not in the Homebridge UI accessories tab. This is correct behaviour for child bridge plugins.
+
+---
+
+## Fan Speed Control — Wiring Mode Note
+
+The Pax Calima and Vent-Axia Svara support two 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.
+
+**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.
+
+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.
+
+To enable full speed control, consult your fan's installation guide to switch to intermittent wiring mode.
+
+---
+
+## 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 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.
+
+---
+
+## 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`
+
+**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.
+
+**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.
+
+**Accessories not appearing in Home app**
+- Remove the accessory cache via Homebridge UI → (plugin settings) → Remove Accessory Cache, then restart Homebridge
+
+---
+
+## Release Notes
+
+### 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
+
+### 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
+
+### 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
+
+### 1.0.x
+- Initial working releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-pax-calima",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "Homebridge platform plugin for Pax Calima and Vent-Axia Svara Bluetooth LE bathroom extractor fans",
   "main": "index.js",
   "keywords": [