homebridge-pax-calima 2.4.2 → 2.4.4

package/README.md

@@ -2,7 +2,7 @@
 
 **Bring your bathroom fan into Apple Home — no hub, no cloud, just Bluetooth.**
 
-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.
+If you have a **Pax Calima** or **Vent-Axia Lo-Carbon Svara** extractor fan, this plugin connects it directly to HomeKit via Bluetooth. Once set up, your fan appears in the Home app with live temperature and fan speed — and you can build automations around all of them.
 
 [![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)
@@ -11,10 +11,10 @@ If you have a **Pax Calima** or **Vent-Axia Lo-Carbon Svara** extractor fan, thi
 
 ## 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.
+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 in the right place.
 
 **Confirmed compatible:**
-- Pax Calima — sold across Scandinavia and Iberia (Sweden, Norway, Denmark, Finland, Spain, Portugal)
+- Pax Calima — Sweden, Norway, Denmark, Finland, Spain, Portugal
 - Vent-Axia Lo-Carbon Svara White — UK
 - Vent-Axia Lo-Carbon Svara Black — UK
 
@@ -24,32 +24,16 @@ These fans are hardware-identical. The same plugin works for all of them.
 
 ## What you get in the Home app
 
-Once set up, your fan appears as a single accessory with these tiles:
+Each fan appears as a single accessory with:
 
-- 🌡️ **Temperature** — live reading, updates every 10 seconds
-- 💡 **Light level** — lux reading, useful for occupancy automations
-- 💨 **Fan speed** — shows current RPM as a percentage
+- 💨 **Fan speed** — shows current RPM as a percentage, live and accurate
+- 🌡️ **Temperature** — live reading, updates every ~20 seconds
 - ⚡ **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)
+- 🌙 **Silent Hours** — keeps the fan quiet at night; set a schedule, a switch, or both (see below)
+- 💧 **Humidity** — available but off by default (read below before enabling)
+- 💡 **Light level** — available but off by default (read below before enabling)
 
-> 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.
-
----
-
-## 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`.
+> Accessories appear in the **Home app on your iPhone**, not the Homebridge UI accessories tab — that's normal for child bridge plugins.
 
 ---
 
@@ -58,9 +42,9 @@ If you still want to enable humidity — perhaps for settled ambient readings ra
 You'll need:
 - Homebridge `^1.6.0` or `^2.0.0`
 - Node.js `18.20.4` or later
-- A Bluetooth adapter on your Homebridge host (the Raspberry Pi 4's built-in adapter works well)
+- A Bluetooth adapter on your Homebridge host (the Pi 4's built-in adapter works well)
 
-**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**:
+**Running Homebridge OS on a Raspberry Pi?** There's one extra step after installation. Run this once in the **Homebridge terminal**:
 
 ```bash
 sudo setcap cap_net_raw+eip /opt/homebridge/bin/node
@@ -72,13 +56,13 @@ If Bluetooth shows as off after that:
 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.
+If things still aren't working after both of those — unplug the Pi, wait 10 seconds, plug it back in. A full power cycle rather than a software restart is sometimes needed to reinitialise the Bluetooth stack cleanly.
 
 ---
 
 ## Installation
 
-Search for **Pax Calima** or **Svara** in the Homebridge UI and click Install — that's it.
+Search for **Pax Calima** or **Svara** in the Homebridge UI and click Install.
 
 Or via terminal:
 ```bash
@@ -89,15 +73,19 @@ npm install -g homebridge-pax-calima
 
 ## Configuration
 
-**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.
+**You don't need to configure anything to get started.** The plugin finds your fan automatically 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:
+A full config example with all options:
 
 ```json
 {
   "platform": "PaxCalima",
   "name": "Pax Calima / Vent-Axia Svara",
+  "silentHoursStart": "23:00",
+  "silentHoursEnd": "07:00",
+  "showSilentSwitch": false,
   "showHumidity": false,
+  "showLight": false,
   "fans": [
     {
       "name": "Wetroom Fan",
@@ -110,83 +98,125 @@ If you want to give your fan a custom name, or if you've set a non-default PIN i
 
 | 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 |
+| `silentHoursStart` | — | Time the fan stops boosting at night, e.g. `"23:00"` |
+| `silentHoursEnd` | — | Time the fan resumes boosting, e.g. `"07:00"` |
+| `showSilentSwitch` | `false` | Adds a Silent Hours switch to the Home app — great for Goodnight scenes |
+| `showHumidity` | `false` | Shows humidity tile — read the note below first |
+| `showLight` | `false` | Shows light tile — read the note below first |
+| `fans[].name` | Auto | Friendly name for a specific fan |
+| `fans[].mac` | — | Only needed to assign a custom name or PIN |
+| `fans[].pin` | `012345` | 6-digit PIN — only change if set via the official app |
 
 ---
 
-## Fan speed control — it depends on how your fan is wired
+## Silent Hours
+
+Silent Hours tells the fan not to boost during a set period — useful for not being woken by a noisy fan at 3am.
+
+**Two ways to use it — pick one or combine both:**
+
+**Schedule (set and forget):** Set `silentHoursStart` and `silentHoursEnd` in your config using 24-hour format. The plugin calculates whether you're in the quiet window on every poll and writes the schedule to the fan automatically. Overnight spans work correctly — `23:00` to `07:00` does what you'd expect.
+
+**Switch (for scenes and shift workers):** Set `showSilentSwitch: true` to add a Silent Hours on/off switch to your accessory. This is ideal for including in a **Goodnight scene** alongside lights and heating — one tap and the fan goes quiet with everything else. It's also the right choice if your sleep schedule changes regularly, like shift work, where a fixed time window doesn't suit.
+
+**Using both together:** If you set a schedule AND enable the switch, the switch takes priority when you toggle it manually. The schedule still runs in the background — useful as a safety net if you forget to turn the switch back on.
+
+---
+
+## A note on humidity and light
+
+Both tiles are **off by default**, and for good reason.
+
+During testing we confirmed that both sensors — while active on the device — don't expose live readings via Bluetooth. The fan uses them internally to decide when to boost, but the BLE characteristic returns the fan's last internal threshold state rather than a continuous measurement. In practical terms:
 
-The Svara and Calima can be installed in two different modes, and which one you have affects what the speed slider does:
+- With all lights off at 21:20, the fan's Bluetooth still reported **52 lux**
+- After a shower that raised the room to **89% humidity**, the Bluetooth still reported **50%**
 
-**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.
+This isn't a bug in the plugin — it's how the fan's firmware works (confirmed on firmware 02.08, and consistent with observations from the Home Assistant community).
 
-**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 turn them on**, be aware that:
+- Asking Siri "what's the humidity in the bathroom?" will likely return a stale number
+- Automations based on these values won't fire reliably
 
-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.
+**What does work well for shower detection:** when the fan's internal humidity sensor detects a sharp rise, it boosts to near full speed automatically. A `Fan Speed > 75%` automation in Apple Home is a reliable, practical trigger for "shower in use."
 
-In either mode, the temperature, light and fan speed automations work perfectly.
+If you want to enable humidity or light anyway — perhaps for settled ambient readings — set `showHumidity: true` or `showLight: true` in your config.
+
+---
+
+## Fan speed control — it depends on how your fan is wired
+
+The fan can be installed in two wiring modes:
+
+**Intermittent mode** — the fan is off by default and spins up when triggered. In this mode the speed slider in Apple Home works as expected.
+
+**Always-on (trickle) mode** — the fan runs continuously at a speed managed by its own controller. Speed commands are accepted via Bluetooth but the fan resets to its own setpoint within seconds. The slider shows the current speed accurately but can't override it.
+
+Not sure which mode you have? If your fan is always running — even quietly — you're in always-on mode. In either mode, temperature, fan speed and automations work perfectly.
 
 ---
 
 ## Something not working?
 
 **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.
+Run `hciconfig` in the Homebridge terminal — you should see `UP RUNNING`. If it shows `RF-KILL`, run `sudo rfkill unblock bluetooth`. If still nothing, unplug the Pi and power cycle it.
 
-**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.
+**setcap not taking effect**
+Make sure you're targeting the right binary — on Homebridge OS it's `/opt/homebridge/bin/node`, not the system Node.
 
-**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.
+**Wrong PIN**
+Default is `012345`. If you changed it in the official app, add the fan to the `fans` config array with the correct PIN.
 
 **Speed slider does nothing**
-Your fan is in always-on mode — see the wiring section above. Everything else still works.
+Your fan is in always-on mode — see above. Everything else works normally.
 
-**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).
+**Humidity or light reading seems stuck**
+This is expected firmware behaviour — see the sensor note above.
 
-**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.
+**Accessories not appearing in Home**
+Go to Homebridge UI → plugin settings → Remove Accessory Cache, then restart. They'll reappear within a few seconds.
 
 ---
 
 ## Homebridge 2.0 compliance
 
-For those who care about the technical details — this plugin meets all Homebridge 2.0 requirements:
+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
+- Waits for `didFinishLaunching` before any BLE or accessory work
+- All errors caught and logged — no unhandled exceptions
+- No analytics, tracking or post-install scripts
+- Accessories restored from cache cleanly without re-registration
 - Compatible with Node.js 18, 20 and 22
 
 ---
 
 ## Release notes
 
+### 2.4.4
+- **Fixed:** Silent Hours time fields no longer show a raw regex pattern as validation hint in the Homebridge UI — replaced with plain human-readable placeholder text (e.g. `23:00`) and a description
+- **Improved:** Invalid time format now logs a clear warning message rather than silently disabling the schedule
+
+### 2.4.3
+- **Silent Hours** reworked — now supports a config schedule (`silentHoursStart` / `silentHoursEnd`) that runs automatically, an optional HomeKit switch (`showSilentSwitch: true`) for Goodnight scenes and irregular schedules, or both together. The switch takes priority when toggled manually; the schedule runs as a background default. Any existing Silent Hours switch from earlier versions is automatically removed unless `showSilentSwitch` is enabled.
+- **Light sensor** (`showLight`) added as opt-in — confirmed via live testing that the characteristic returns a static value regardless of lighting conditions.
+- **`showSilentSwitch`**, **`showHumidity`** and **`showLight`** grouped under "Optional Sensors" in the Homebridge UI config for a cleaner settings experience.
+- **`displayName`** added to `package.json` — shows correctly as "Vent-Axia Svara / Pax Calima" in the Homebridge UI.
+- Sensor characteristic only read when at least one optional sensor is enabled — slightly leaner poll cycle for most users.
+- Silent Hours written to fan on every poll — stays in sync after power cuts.
+
 ### 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
+- Humidity sensor disabled by default — opt-in via `showHumidity: true`
+- README rewritten with a more human tone
 
 ### 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
+- Fixed sensors returning stale values — reverted to connect→read→disconnect per poll
 
 ### 2.4.0
-- 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
+- Rebuilt with persistent connection architecture
 
-### 2.2.1 / 2.1.0
+### 2.3.x / 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
+- Homebridge 2.0 initialisation fixes; duplicate accessory registration resolved
 
 ### 1.0.x
 - Initial releases

package/config.schema.json

@@ -10,15 +10,39 @@
         "type": "string",
         "default": "Pax Calima / Vent-Axia Svara"
       },
+      "silentHoursStart": {
+        "title": "Silent Hours — Start Time",
+        "type": "string",
+        "placeholder": "23:00",
+        "description": "When the fan stops boosting at night. Enter in 24-hour format, e.g. 23:00. Leave blank to disable the schedule."
+      },
+      "silentHoursEnd": {
+        "title": "Silent Hours — End Time",
+        "type": "string",
+        "placeholder": "07:00",
+        "description": "When the fan resumes boosting in the morning. Enter in 24-hour format, e.g. 07:00. Both start and end must be set for the schedule to activate."
+      },
+      "showSilentSwitch": {
+        "title": "Show Silent Hours Switch in Home",
+        "type": "boolean",
+        "default": false,
+        "description": "Adds a Silent Hours on/off switch to your accessory in the Home app. Useful for including in a Goodnight scene or automation. Good for shift workers or irregular schedules."
+      },
       "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."
+        "description": "⚠️ The fan's humidity reading reflects its internal threshold state and updates infrequently — it is NOT a live sensor reading and is NOT suitable for Siri queries or real-time automations. Only enable if you understand and accept this limitation."
+      },
+      "showLight": {
+        "title": "Show Light Sensor",
+        "type": "boolean",
+        "default": false,
+        "description": "⚠️ The fan's light reading reflects its internal threshold state and updates infrequently — it is NOT a live lux reading. Confirmed via testing: the value remains static regardless of lighting conditions. Only enable if you understand this limitation."
       },
       "fans": {
         "title": "Manually Configured Fans",
-        "description": "Optional. Leave empty to use auto-discovery. Add entries here only to set a custom name or PIN per fan.",
+        "description": "Optional. Leave empty for auto-discovery. Add entries here only to set a custom name or PIN per fan.",
         "type": "array",
         "items": {
           "type": "object",
@@ -31,8 +55,8 @@
             "mac": {
               "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)"
+              "placeholder": "58:2b:db:xx:xx:xx",
+              "description": "MAC address of the fan — found in the official Pax or Vent-Axia app under About Device."
             },
             "pin": {
               "title": "PIN Code",
@@ -49,9 +73,17 @@
   "layout": [
     {
       "type": "section",
-      "title": "General",
-      "expandable": false,
-      "items": ["name", "showHumidity"]
+      "title": "Silent Hours",
+      "expandable": true,
+      "expanded": false,
+      "items": ["silentHoursStart", "silentHoursEnd", "showSilentSwitch"]
+    },
+    {
+      "type": "section",
+      "title": "Optional Sensors",
+      "expandable": true,
+      "expanded": false,
+      "items": ["showHumidity", "showLight"]
     },
     {
       "type": "section",

package/index.js

@@ -5,15 +5,36 @@ const noble = require('@abandonware/noble');
 let Service, Characteristic, Categories, API, PlatformAccessory;
 
 // ── 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 UUID_AUTH    = '4cad343a-209a-40b7-b911-4d9b3df569b2'; // PIN auth
+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 [trickle|normal|boost] UInt16LE
+const UUID_SILENT  = 'b5836b55-57bd-433e-8480-46e4993c5ac0'; // silent hours [enabled, startH, startM, endH, endM]
 
 const MAC_PREFIX   = '58:2b:db';
 const POLL_MS      = 10000;
 const RECONNECT_MS = 15000;
 
+function parseTime(str, label) {
+  if (!str || typeof str !== 'string') return null;
+  const parts = str.split(':');
+  if (parts.length !== 2 || parts[0] === '' || parts[1] === '') {
+    console.warn('[PaxCalima] ' + (label || 'Silent Hours') + ' time "' + str + '" is not valid — use 24-hour format e.g. 23:00. Silent Hours schedule disabled.');
+    return null;
+  }
+  const hour   = parseInt(parts[0], 10);
+  const minute = parseInt(parts[1], 10);
+  if (isNaN(hour) || isNaN(minute) || hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    console.warn('[PaxCalima] ' + (label || 'Silent Hours') + ' time "' + str + '" is out of range — use 24-hour format e.g. 23:00. Silent Hours schedule disabled.');
+    return null;
+  }
+  return { hour, minute };
+}
+
+function timeStr(t) {
+  return String(t.hour).padStart(2, '0') + ':' + String(t.minute).padStart(2, '0');
+}
+
 module.exports = (homebridge) => {
   Service           = homebridge.hap.Service;
   Characteristic    = homebridge.hap.Characteristic;
@@ -62,7 +83,7 @@ class PaxCalimaPlatform {
 
     for (const { accessory, mac } of this.cachedAccessories) {
       this.log.info('Starting handler for cached fan: ' + mac);
-      new PaxCalimaAccessory(this.log, accessory, mac, this.pinForMac(mac), this.showHumidity());
+      new PaxCalimaAccessory(this.log, accessory, mac, this.fanOptions(mac));
     }
     this.cachedAccessories = [];
 
@@ -73,39 +94,50 @@ 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 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, this.pinForMac(mac), this.showHumidity());
+      new PaxCalimaAccessory(this.log, hbAcc, mac, this.fanOptions(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 || ('Pax Calima ' + mac.slice(-5).toUpperCase()); }
-  showHumidity()    { return this.config.showHumidity === true; }
+  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()); }
+
+  fanOptions(mac) {
+    return {
+      pin:               this.pinForMac(mac),
+      showHumidity:      this.config.showHumidity    === true,
+      showLight:         this.config.showLight        === true,
+      showSilentSwitch:  this.config.showSilentSwitch === true,
+      silentHoursStart:  this.config.silentHoursStart || null,
+      silentHoursEnd:    this.config.silentHoursEnd   || null,
+    };
+  }
 }
 
 // ─── Accessory ────────────────────────────────────────────────────────────────
 class PaxCalimaAccessory {
-  constructor(log, accessory, mac, pin, showHumidity) {
-    this.log          = log;
-    this.accessory    = accessory;
-    this.mac          = mac.toLowerCase();
-    this.pin          = pin || '012345';
-    this.showHumidity = showHumidity;
+  constructor(log, accessory, mac, options) {
+    this.log              = log;
+    this.accessory        = accessory;
+    this.mac              = mac.toLowerCase();
+    this.pin              = options.pin              || '012345';
+    this.showHumidity     = options.showHumidity     || false;
+    this.showLight        = options.showLight        || false;
+    this.showSilentSwitch = options.showSilentSwitch || false;
+    this.silentStart      = parseTime(options.silentHoursStart, 'silentHoursStart');
+    this.silentEnd        = parseTime(options.silentHoursEnd, 'silentHoursEnd');
 
     this.currentRPM  = 0;
     this.humidity    = 0;
     this.temperature = 20;
     this.lightLevel  = 0.0001;
-    this.silentHours = false;
+    this.silentHours = false; // runtime state of the silent hours switch
 
     this.pollTimer = null;
     this.polling   = false;
@@ -114,10 +146,11 @@ class PaxCalimaAccessory {
     this.schedulePoll(0);
   }
 
+  // ── Services ────────────────────────────────────────────────────────────────
   setupServices() {
     const n = this.accessory.displayName;
 
-    // Fan — always active; speed reflects live RPM
+    // Fan speed — always present
     this.fanService = this.accessory.getService(Service.Fanv2)
       || this.accessory.addService(new Service.Fanv2(n, 'fan'));
     this.fanService.getCharacteristic(Characteristic.Active)
@@ -127,49 +160,67 @@ class PaxCalimaAccessory {
       .onGet(() => this.rpmToPercent(this.currentRPM))
       .onSet((v) => this.writeSpeed(v));
 
-    // Boost — stateless single-press button
+    // Boost button — always present
     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
-    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));
-
-    // Temperature
+    // Temperature — always present
     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));
+    // Silent Hours switch — opt-in via showSilentSwitch: true
+    // Coexists with config schedule — switch state takes priority on next poll
+    if (this.showSilentSwitch) {
+      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.silentHours = on;
+          this.log.info('Silent Hours manually ' + (on ? 'enabled' : 'disabled'));
+        });
+      this.log.info('Silent Hours switch enabled');
+    } else {
+      // Remove switch if it was registered in a previous version
+      const existing = this.accessory.getServiceByUUIDAndSubType(Service.Switch, 'silent-hours');
+      if (existing) {
+        this.accessory.removeService(existing);
+        this.log.info('Silent Hours switch removed — use config schedule or enable showSilentSwitch');
+      }
+    }
 
-    // Humidity — optional, disabled by default due to firmware update frequency limitations
-    // User must explicitly enable via showHumidity: true in config
+    // Humidity — opt-in only
     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');
+      this.log.info('Humidity sensor enabled — reflects fan internal 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)');
+    }
+
+    // Light — opt-in only
+    if (this.showLight) {
+      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));
+      this.log.info('Light sensor enabled — reflects fan internal state, not real-time');
+    } else {
+      const existing = this.accessory.getService(Service.LightSensor);
+      if (existing) this.accessory.removeService(existing);
     }
 
     this.log.info('Services ready: ' + n);
   }
 
+  // ── Poll cycle ──────────────────────────────────────────────────────────────
   schedulePoll(delayMs) {
     if (this.pollTimer) clearTimeout(this.pollTimer);
     this.pollTimer = setTimeout(() => this.poll(), delayMs);
@@ -184,7 +235,6 @@ class PaxCalimaAccessory {
       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) {
@@ -199,43 +249,69 @@ class PaxCalimaAccessory {
       pinBuf.writeUInt32LE(parseInt(this.pin, 10), 0);
       await authChar.writeAsync(pinBuf, true);
 
-      // Read status: RPM + temperature — updates live on every connection
+      // Read 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;
 
-      // Read sensor characteristic only if humidity is enabled
-      // The device updates this characteristic infrequently (firmware limitation)
-      if (this.showHumidity) {
+      // Read sensor characteristic only if humidity or light is enabled
+      if (this.showHumidity || this.showLight) {
         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));
+          if (this.showHumidity) this.humidity   = Math.max(0, Math.min(100, sensorData.readUInt8(0) * 2));
+          if (this.showLight)    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));
+      }
+
+      // Determine silent hours state:
+      // If switch is shown, the user's manual toggle takes priority.
+      // If no switch, derive from config schedule based on current time.
+      let silentActive = this.silentHours; // default: use switch state
+      if (!this.showSilentSwitch && this.silentStart && this.silentEnd) {
+        silentActive = this.isWithinSilentHours();
+      }
+
+      // Write silent hours to fan on every poll
+      const silentChar = charCache[UUID_SILENT.replace(/-/g, '')];
+      if (silentChar && (this.showSilentSwitch || (this.silentStart && this.silentEnd))) {
+        const buf = Buffer.alloc(5);
+        if (this.showSilentSwitch) {
+          // Switch mode: enabled flag driven by switch; use config times if set, else 00:00–00:00
+          buf.writeUInt8(this.silentHours ? 1 : 0, 0);
+          buf.writeUInt8(this.silentStart ? this.silentStart.hour   : 0, 1);
+          buf.writeUInt8(this.silentStart ? this.silentStart.minute : 0, 2);
+          buf.writeUInt8(this.silentEnd   ? this.silentEnd.hour     : 0, 3);
+          buf.writeUInt8(this.silentEnd   ? this.silentEnd.minute   : 0, 4);
+        } else {
+          // Schedule mode: always enabled, times from config
+          buf.writeUInt8(1, 0);
+          buf.writeUInt8(this.silentStart.hour,   1);
+          buf.writeUInt8(this.silentStart.minute, 2);
+          buf.writeUInt8(this.silentEnd.hour,     3);
+          buf.writeUInt8(this.silentEnd.minute,   4);
         }
+        await silentChar.writeAsync(buf, true);
       }
 
       // 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) {
+      if (this.showSilentSwitch && this.silentService)
+        this.silentService.getCharacteristic(Characteristic.On).updateValue(this.silentHours);
+      if (this.showHumidity && this.humidityService)
         this.humidityService.getCharacteristic(Characteristic.CurrentRelativeHumidity).updateValue(this.humidity);
-      }
+      if (this.showLight && this.lightService)
+        this.lightService.getCharacteristic(Characteristic.CurrentAmbientLightLevel).updateValue(this.lightLevel);
 
       this.log.info('Poll: RPM=' + this.currentRPM + ' Speed=' + speed +
-        '% Temp=' + this.temperature + 'C Light=' + this.lightLevel + 'lx' +
-        (this.showHumidity ? ' Hum=' + this.humidity + '%' : ''));
+        '% Temp=' + this.temperature + 'C' +
+        (this.showSilentSwitch || (this.silentStart && this.silentEnd) ? ' Silent=' + (silentActive ? 'on' : 'off') : '') +
+        (this.showHumidity ? ' Hum=' + this.humidity + '%' : '') +
+        (this.showLight    ? ' Light=' + this.lightLevel + 'lx' : ''));
 
     } catch (err) {
       this.log.warn('Poll error: ' + err.message);
@@ -246,6 +322,18 @@ class PaxCalimaAccessory {
     }
   }
 
+  // Returns true if current time falls within the silent hours window
+  isWithinSilentHours() {
+    if (!this.silentStart || !this.silentEnd) return false;
+    const now     = new Date();
+    const current = now.getHours() * 60 + now.getMinutes();
+    const start   = this.silentStart.hour * 60 + this.silentStart.minute;
+    const end     = this.silentEnd.hour   * 60 + this.silentEnd.minute;
+    // Handle overnight spans e.g. 23:00 → 07:00
+    if (start > end) return current >= start || current < end;
+    return current >= start && current < end;
+  }
+
   findPeripheral() {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
@@ -264,6 +352,7 @@ class PaxCalimaAccessory {
     });
   }
 
+  // ── Fan speed write ─────────────────────────────────────────────────────────
   async writeSpeed(percent) {
     if (this.polling) { this.log.warn('Speed write skipped — poll in progress'); return; }
     let peripheral = null;
@@ -296,11 +385,6 @@ class PaxCalimaAccessory {
     }
   }
 
-  async setSilentHours(on) {
-    this.silentHours = on;
-    this.log.info('Silent Hours ' + (on ? 'enabled' : 'disabled'));
-  }
-
   rpmToPercent(rpm) {
     return Math.min(100, Math.max(0, Math.round(rpm / 25)));
   }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "homebridge-pax-calima",
-  "version": "2.4.2",
-  "description": "Homebridge platform plugin for Pax Calima and Vent-Axia Svara Bluetooth LE bathroom extractor fans",
+  "displayName": "Vent-Axia Svara / Pax Calima",
+  "version": "2.4.4",
+  "description": "Bring your Pax Calima or Vent-Axia Svara bathroom fan into Apple Home via Bluetooth — live temperature and fan speed with Silent Hours scheduling and full automation support.",
   "main": "index.js",
   "keywords": [
     "homebridge-plugin",