@smarterhomeapp/homebridge-vantage 1.0.8 → 1.1.4

package/README.md

@@ -11,8 +11,9 @@ This plugin replaces the one sold on smarterhome.io allowing anyone to download
 - **Blind Control**: Window covering automation
 - **Real-time Updates**: Live status updates from your InFusion controller
 - **SSL Support**: Secure connections to your controller
-- **Device Filtering**: Include/exclude specific devices by VID range
+- **Device Filtering**: Include or exclude devices by type, omit list, or VID range
 - **Safe Configuration Cache**: Downloads fresh controller configuration on every startup while keeping a persistent last-known-good fallback
+- **Controller Discovery**: Uses the configured IP first, then mDNS if that address does not respond
 
 ## Installation
 
@@ -37,25 +38,37 @@ npm install -g @smarterhomeapp/homebridge-vantage
       "username": "your_username",
       "password": "your_password",
       "usecache": true,
+      "forceSSL": false,
+      "includeLights": true,
+      "includeBlinds": true,
+      "includeThermostats": true,
+      "includeSensors": true,
       "omit": "1234,5678",
-      "range": "1000,2000"
+      "range": "0-2290"
     }
   ]
 }
 ```
 
+`platform` must stay `"VantageControls"`. `name` is only a label for logs and the Config UI.
+
 ## Configuration
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `platform` | string | Yes | Must be "VantageControls" |
-| `name` | string | Yes | Display name for the platform |
-| `ipaddress` | string | Yes | IP address of your InFusion controller |
-| `username` | string | No | Username for authentication |
-| `password` | string | No | Password for authentication |
-| `usecache` | boolean | No | Maintain a persistent last-known-good configuration fallback while still attempting fresh controller discovery on every startup (default: true) |
+| `platform` | string | Yes | Must be `"VantageControls"` |
+| `name` | string | Yes | Display name for this platform entry |
+| `ipaddress` | string | No | Controller IP. Leave blank to discover an InFusion controller with mDNS. If a configured IP stops responding, the plugin also tries mDNS. |
+| `username` | string | No | Username for authentication. If login fails or times out, the plugin still attempts the configuration download. The common typo `admin` is retried as `administrator`. |
+| `password` | string | No | Password for authentication. Used with `username`; a rejected login does not skip discovery. |
+| `forceSSL` | boolean | No | Skip insecure ports and use 3010/2010 directly (default: false) |
+| `usecache` | boolean | No | Maintain a persistent last-known-good configuration fallback while still attempting fresh controller discovery on every startup (default: true). If this is off and a live download fails, existing HomeKit accessories are kept. |
+| `includeLights` | boolean | No | Include Vantage loads, dimmers, relays, RGB loads, and similar switch/light devices (default: true) |
+| `includeBlinds` | boolean | No | Include Vantage blinds, shades, and window coverings (default: true) |
+| `includeThermostats` | boolean | No | Include Vantage thermostats and HVAC zones (default: true) |
+| `includeSensors` | boolean | No | Include dry contacts, temperature sensors, light sensors, and Omni sensors (default: true) |
 | `omit` | string | No | Comma-separated list of VIDs to exclude |
-| `range` | string | No | Comma-separated VID range (min,max) |
+| `range` | string | No | VID range using `min-max`, e.g. `1000-2000`. Legacy comma format, e.g. `1000,2000`, is still supported. |
 
 ## Configuration Discovery and Cache
 
@@ -65,6 +78,43 @@ When `usecache` is enabled, the persistent cache is only a fallback. If the cont
 
 The cache is stored under Homebridge's configured storage directory in a plugin-specific `vantage` folder. Cache filenames are keyed by controller IP, for example `vantage-10.0.0.100.dc`, so multiple platform instances using different VID ranges for the same controller share one full-controller cache. Restarts naturally pick up controller/DC changes; users do not need to manually clear the cache.
 
+The plugin also writes a copy to `/tmp/vantage.dc` for local tools such as Organize Home. That dump is updated from the configuration Homebridge actually uses: a successful live download, or the persistent last-known-good cache if live discovery fails. Incomplete or rejected downloads are not written there.
+
+## HomeKit Accessory Limit and Child Bridges
+
+HomeKit allows about 149 accessories on one bridge. If discovery finds more than that, split the controller with two `VantageControls` entries and different `range` values.
+
+On Homebridge 2, every extra instance of the same dynamic platform must be a child bridge. Put `_bridge` on each split instance, with a unique username and port. Each child bridge is paired separately in the Home app.
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "VantageControls",
+      "name": "Vantage Low",
+      "ipaddress": "192.168.1.100",
+      "range": "0-2290",
+      "_bridge": {
+        "username": "0E:AA:BB:CC:DD:02",
+        "port": 51839
+      }
+    },
+    {
+      "platform": "VantageControls",
+      "name": "Vantage High",
+      "ipaddress": "192.168.1.100",
+      "range": "2291-999999999",
+      "_bridge": {
+        "username": "0E:AA:BB:CC:DD:03",
+        "port": 51840
+      }
+    }
+  ]
+}
+```
+
+Homebridge 1.x still accepts one instance on the main bridge and one child bridge. That layout is rejected on Homebridge 2.
+
 ## Supported Devices
 
 ### Lighting
@@ -81,6 +131,13 @@ The cache is stored under Homebridge's configured storage directory in a plugin-
 - **Blinds**: Position control (0-100%)
 - **Shades**: Motorized window coverings
 
+### Sensors
+- **Dry contacts**: Contact sensors, including motion-style contacts
+- **Temperature and Omni sensors**: Indoor temperature and similar Omni values
+- **Light sensors**: Ambient light level
+
+Load groups and blind groups are not exposed as HomeKit accessories. Use HomeKit rooms or scenes to group devices.
+
 ## Development
 
 1. Clone the repository:
@@ -107,13 +164,14 @@ npm link
 ## Troubleshooting
 
 ### Connection Issues
-- Verify the IP address is correct
+- Verify the IP address is correct, or leave it blank so mDNS can find the controller
 - Check if SSL is required (ports 3010/2010 vs 3001/2001)
 - Ensure username/password are correct if authentication is enabled
 
 ### Device Not Appearing
 - Check the `omit` and `range` parameters
 - Verify the device VID is within the specified range
+- On Homebridge 2, pair each child bridge in the Home app. The main hub may have no Vantage devices.
 - Check Homebridge logs for discovery errors
 
 ### Performance Issues

package/config.schema.json

@@ -10,28 +10,27 @@
       "name": {
         "title": "Name",
         "type": "string",
-        "default": "VantageControls",
-        "description": "A label for this platform entry."
+        "default": "Vantage Controls",
+        "description": "A label for this platform entry. This is not the Homebridge platform identifier."
       },
       "ipaddress": {
         "title": "Controller IP",
         "type": "string",
-        "format": "ipv4",
         "placeholder": "192.168.1.50",
-        "description": "IP address of your Vantage InFusion controller."
+        "description": "IP address of your Vantage InFusion controller. Leave blank to discover an InFusion controller using mDNS."
       },
       "username": {
         "title": "Username",
         "type": "string",
         "placeholder": "optional",
-        "description": "Only needed if your controller requires login."
+        "description": "Only needed if your controller requires login. If login is rejected or times out, discovery still continues."
       },
       "password": {
         "title": "Password",
         "type": "string",
         "format": "password",
         "placeholder": "optional",
-        "description": "Only needed if your controller requires login."
+        "description": "Only needed if your controller requires login. Used with Username."
       },
       "forceSSL": {
         "title": "Force SSL",
@@ -43,7 +42,31 @@
         "title": "Use Local Cache",
         "type": "boolean",
         "default": true,
-        "description": "Use previously downloaded configuration (if present) to speed up startup."
+        "description": "Maintain a persistent last-known-good configuration fallback while still attempting fresh discovery on startup."
+      },
+      "includeLights": {
+        "title": "Include Lights and Loads",
+        "type": "boolean",
+        "default": true,
+        "description": "Create HomeKit accessories for Vantage loads, dimmers, relays, RGB loads, and similar switch/light devices."
+      },
+      "includeBlinds": {
+        "title": "Include Blinds and Shades",
+        "type": "boolean",
+        "default": true,
+        "description": "Create HomeKit accessories for Vantage blinds, shades, and window coverings."
+      },
+      "includeThermostats": {
+        "title": "Include Thermostats",
+        "type": "boolean",
+        "default": true,
+        "description": "Create HomeKit accessories for Vantage thermostats and HVAC zones."
+      },
+      "includeSensors": {
+        "title": "Include Sensors and Contacts",
+        "type": "boolean",
+        "default": true,
+        "description": "Create HomeKit accessories for dry contacts, temperature sensors, light sensors, and Omni sensors."
       },
       "omit": {
         "title": "Omit VIDs",
@@ -54,12 +77,12 @@
       "range": {
         "title": "VID Range",
         "type": "string",
-        "default": "0,999999999",
-        "placeholder": "0,999999999",
-        "description": "Include only VIDs within this inclusive range, e.g. 0,5000. If you have more than 140 loads, add 2 instances of the vantage platform with different ranges."
+        "default": "0-999999999",
+        "placeholder": "0-999999999",
+        "description": "Include only VIDs within this inclusive range, e.g. 0-5000. Legacy comma format such as 0,5000 is still supported. If you have more than 140 accessories, add another VantageControls platform with a different range. On Homebridge 2, every extra instance must be a child bridge."
       }
     },
-    "required": ["name", "ipaddress"],
+    "required": ["name"],
     "additionalProperties": false
   },
 
@@ -73,6 +96,13 @@
     },
     "forceSSL",
     "usecache",
+    {
+      "type": "fieldset",
+      "title": "Device Types",
+      "expandable": true,
+      "expanded": true,
+      "items": ["includeLights", "includeBlinds", "includeThermostats", "includeSensors"]
+    },
     {
       "type": "fieldset",
       "title": "Advanced",

package/dist/homekitName.d.ts

@@ -0,0 +1,2 @@
+/** HomeKit/HAP 2.3 accessory names must start and end with a letter or number. */
+export declare function sanitizeHomeKitName(raw: string, fallback?: string): string;

package/dist/homekitName.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeHomeKitName = sanitizeHomeKitName;
+const HAP_NAME_PATTERN = /^[\p{L}\p{N}](?:[\p{L}\p{N}\p{Zs}\u2019'&!._:;()/,-]*[\p{L}\p{N}])?$/u;
+/** HomeKit/HAP 2.3 accessory names must start and end with a letter or number. */
+function sanitizeHomeKitName(raw, fallback = 'Vantage') {
+    let name = String(raw ?? '').normalize('NFC');
+    name = name.replace(/[()]/g, ' ');
+    name = name.replace(/[^\p{L}\p{N}\p{Zs}\u2019'&!._:;()/,-]+/gu, ' ');
+    name = name.replace(/\p{Zs}+/gu, ' ').trim();
+    name = name.replace(/^[^\p{L}\p{N}]+/u, '').replace(/[^\p{L}\p{N}]+$/u, '').trim();
+    if (name && HAP_NAME_PATTERN.test(name)) {
+        return name;
+    }
+    name = name.replace(/[^\p{L}\p{N}\p{Zs}]+/gu, ' ').replace(/\p{Zs}+/gu, ' ').trim();
+    return name || fallback;
+}

package/dist/platform.d.ts

@@ -9,6 +9,7 @@ export declare class VantagePlatform implements DynamicPlatformPlugin {
     private syncedOnce;
     private accessoriesByVid;
     private realtimeWired;
+    private invalidThermostatWarnings;
     constructor(log: Logger, config: PlatformConfig, api: API);
     configureAccessory(accessory: PlatformAccessory): void;
     private syncAccessories;
@@ -16,6 +17,12 @@ export declare class VantagePlatform implements DynamicPlatformPlugin {
     private rebuildAccessoryVidMap;
     private wireRealtimeListeners;
     private finalizeLogs;
+    private normalizeCurrentTemperature;
+    private normalizeTargetTemperature;
+    private isValidTargetTemperature;
+    private ensureValidThermostatSetpoints;
+    private resolveAutoModeTargetTemperature;
+    private logInvalidThermostatValue;
     getInfusion(): VantageInfusion;
     getApi(): API;
 }

package/dist/platform.js

@@ -4,6 +4,7 @@ exports.VantagePlatform = void 0;
 const settings_1 = require("./settings");
 const vantageInfusion_1 = require("./vantageInfusion");
 const platformAccessory_1 = require("./platformAccessory");
+const homekitName_1 = require("./homekitName");
 class VantagePlatform {
     constructor(log, config, api) {
         this.log = log;
@@ -13,19 +14,24 @@ class VantagePlatform {
         this.syncedOnce = false; // prevent double-sync when both event + promise fire
         this.accessoriesByVid = new Map();
         this.realtimeWired = false;
-        if (!config || !config.ipaddress) {
-            this.log.error(`[${settings_1.PLATFORM_NAME}] Missing required config "ipaddress" — plugin will not start.`);
+        this.invalidThermostatWarnings = new Set();
+        if (!config) {
+            this.log.error(`[${settings_1.PLATFORM_NAME}] Missing platform config — plugin will not start.`);
             return;
         }
         // Construct infusion
         this.infusion = new vantageInfusion_1.VantageInfusion({
-            ipaddress: String(config.ipaddress),
+            ipaddress: config.ipaddress ? String(config.ipaddress) : '',
             username: config.username ?? '',
             password: config.password ?? '',
             usecache: config.usecache ?? true,
             omit: config.omit ?? '',
-            range: config.range ?? '0,999999999',
+            range: config.range ?? '0-999999999',
             forceSSL: config.forceSSL ?? false,
+            includeLights: config.includeLights ?? true,
+            includeBlinds: config.includeBlinds ?? true,
+            includeThermostats: config.includeThermostats ?? true,
+            includeSensors: config.includeSensors ?? true,
             storagePath: this.api.user.storagePath(),
             log: this.log,
         });
@@ -79,7 +85,7 @@ class VantagePlatform {
             const d = wanted.get(acc.UUID);
             if (d) {
                 // Update name/context and re-bind
-                acc.displayName = d.name;
+                acc.displayName = (0, homekitName_1.sanitizeHomeKitName)(d.name, `VID ${d.vid}`);
                 acc.context.device = d;
                 new platformAccessory_1.VantagePlatformAccessory(this, acc);
                 seen.add(acc.UUID);
@@ -98,7 +104,7 @@ class VantagePlatform {
             const uuid = uuidFor(d);
             if (seen.has(uuid))
                 continue;
-            const acc = new this.api.platformAccessory(d.name, uuid);
+            const acc = new this.api.platformAccessory((0, homekitName_1.sanitizeHomeKitName)(d.name, `VID ${d.vid}`), uuid);
             acc.context.device = d;
             new platformAccessory_1.VantagePlatformAccessory(this, acc);
             toRegister.push(acc);
@@ -234,11 +240,10 @@ class VantagePlatform {
             if (!acc)
                 return;
             const dev = acc.context.device;
-            let temperature = Number(temp);
-            // Validate temperature range (from original code)
-            if (temperature > 100) {
-                temperature = 100;
-                this.log.warn(`Thermostat ${vid} reported invalid temperature ${temp}°C, capping at 100°C`);
+            const temperature = this.normalizeCurrentTemperature(temp);
+            if (temperature === undefined) {
+                this.logInvalidThermostatValue(`${vid}:current`, `Thermostat ${vid} reported invalid temperature ${temp}; ignoring update`);
+                return;
             }
             dev.temperature = temperature;
             this.log.info(`thermostatIndoorTemperatureChange (VID=${vid}, Name=${dev.name}, Temp=${temperature})`);
@@ -274,35 +279,174 @@ class VantagePlatform {
                 dev.current = current; // Store the calculated current state
                 svc.updateCharacteristic(C.CurrentHeatingCoolingState, current);
                 svc.updateCharacteristic(C.TargetHeatingCoolingState, mode);
+                this.ensureValidThermostatSetpoints(dev, svc);
             }
             else {
-                dev.targetTemp = Math.min(38, targetTemp);
+                const normalizedTarget = this.normalizeTargetTemperature(targetTemp);
+                if (normalizedTarget === undefined) {
+                    this.logInvalidThermostatValue(`${vid}:target`, `Thermostat ${vid} reported invalid target temperature ${targetTemp}; ignoring setpoint update`);
+                    svc.updateCharacteristic(C.TargetHeatingCoolingState, mode);
+                    this.ensureValidThermostatSetpoints(dev, svc);
+                    return;
+                }
+                dev.mode = mode;
+                dev.targetTemp = normalizedTarget;
                 if (mode === 1) {
-                    dev.heating = Math.min(25, targetTemp); // HomeKit max is 25°C
+                    dev.heating = Math.min(25, normalizedTarget); // HomeKit max is 25°C
                     svc.updateCharacteristic(C.HeatingThresholdTemperature, dev.heating);
                 }
                 else if (mode === 2) {
-                    dev.cooling = Math.min(35, targetTemp);
+                    dev.cooling = Math.min(35, normalizedTarget);
                     svc.updateCharacteristic(C.CoolingThresholdTemperature, dev.cooling);
                 }
                 // Update target temperature based on mode (from original logic)
-                if (dev.mode === 1)
+                if (dev.mode === 1 && this.isValidTargetTemperature(dev.heating)) {
                     dev.targetTemp = dev.heating;
-                else if (dev.mode === 2)
+                }
+                else if (dev.mode === 2 && this.isValidTargetTemperature(dev.cooling)) {
                     dev.targetTemp = dev.cooling;
-                else if (dev.mode === 3)
-                    dev.targetTemp = (dev.temperature <= dev.heating) ? dev.heating : dev.cooling;
-                svc.updateCharacteristic(C.TargetTemperature, dev.targetTemp);
+                }
+                else if (dev.mode === 3) {
+                    const target = this.resolveAutoModeTargetTemperature(dev);
+                    if (target !== undefined) {
+                        dev.targetTemp = target;
+                    }
+                }
+                if (this.isValidTargetTemperature(dev.targetTemp)) {
+                    svc.updateCharacteristic(C.TargetTemperature, dev.targetTemp);
+                }
                 svc.updateCharacteristic(C.TargetHeatingCoolingState, dev.mode);
                 // this.log.info(`After update - dev.mode=${dev.mode}, dev.targetTemp=${dev.targetTemp}, dev.heating=${dev.heating}, dev.cooling=${dev.cooling}`);
             }
         });
+        this.infusion.on('thermostatChildTemperatureChange', (vid, role, temperature) => {
+            const acc = this.accessoriesByVid.get(String(vid));
+            if (!acc)
+                return;
+            const dev = acc.context.device;
+            const svc = acc.getService(S.Thermostat);
+            if (!svc || !dev || dev.type !== 'thermostat')
+                return;
+            const normalized = role === 'indoor'
+                ? this.normalizeCurrentTemperature(temperature)
+                : this.normalizeTargetTemperature(temperature);
+            if (normalized === undefined) {
+                this.logInvalidThermostatValue(`${vid}:${role}`, `Thermostat ${vid} reported invalid ${role} temperature ${temperature}; ignoring update`);
+                return;
+            }
+            if (role === 'indoor') {
+                dev.temperature = normalized;
+                svc.updateCharacteristic(C.CurrentTemperature, normalized);
+                return;
+            }
+            if (role === 'heat') {
+                dev.heating = normalized;
+                svc.updateCharacteristic(C.HeatingThresholdTemperature, Math.min(25, Math.max(10, normalized)));
+                if (dev.mode === 1) {
+                    dev.targetTemp = normalized;
+                    svc.updateCharacteristic(C.TargetTemperature, normalized);
+                }
+                return;
+            }
+            if (role === 'cool') {
+                dev.cooling = normalized;
+                svc.updateCharacteristic(C.CoolingThresholdTemperature, Math.min(35, Math.max(10, normalized)));
+                if (dev.mode === 2) {
+                    dev.targetTemp = normalized;
+                    svc.updateCharacteristic(C.TargetTemperature, normalized);
+                }
+            }
+        });
+        this.infusion.on('contactStatusChange', (vid, contact) => {
+            const acc = this.accessoriesByVid.get(String(vid));
+            if (!acc)
+                return;
+            const dev = acc.context.device;
+            if (!dev || dev.type !== 'contact')
+                return;
+            dev.contact = contact;
+            acc.getService(S.ContactSensor)?.updateCharacteristic(C.ContactSensorState, contact ? C.ContactSensorState.CONTACT_DETECTED : C.ContactSensorState.CONTACT_NOT_DETECTED);
+        });
+        this.infusion.on('temperatureSensorChange', (vid, temperature) => {
+            const acc = this.accessoriesByVid.get(String(vid));
+            if (!acc)
+                return;
+            const dev = acc.context.device;
+            if (!dev || dev.type !== 'temperatureSensor')
+                return;
+            const normalized = Math.min(100, Math.max(-50, Number(temperature)));
+            dev.temperature = normalized;
+            acc.getService(S.TemperatureSensor)?.updateCharacteristic(C.CurrentTemperature, normalized);
+        });
+        this.infusion.on('lightSensorChange', (vid, lightLevel) => {
+            const acc = this.accessoriesByVid.get(String(vid));
+            if (!acc)
+                return;
+            const dev = acc.context.device;
+            if (!dev || dev.type !== 'lightSensor')
+                return;
+            const normalized = Math.max(0.0001, Math.min(100000, Number(lightLevel)));
+            dev.lightLevel = normalized;
+            acc.getService(S.LightSensor)?.updateCharacteristic(C.CurrentAmbientLightLevel, normalized);
+        });
     }
     finalizeLogs() {
         // Legacy “store/open for business” logs
         this.log.warn('VantagePlatform for InFusion Controller (end configuration store)');
         this.log.warn('VantagePlatform for InFusion Controller (is open for business)');
     }
+    normalizeCurrentTemperature(value) {
+        const temperature = Number(value);
+        if (!Number.isFinite(temperature) || temperature <= -100 || temperature >= 900)
+            return undefined;
+        return Math.min(100, Math.max(-50, temperature));
+    }
+    normalizeTargetTemperature(value) {
+        const temperature = Number(value);
+        if (!Number.isFinite(temperature) || temperature < 1 || temperature >= 900)
+            return undefined;
+        return Math.min(38, Math.max(10, temperature));
+    }
+    isValidTargetTemperature(value) {
+        const temperature = Number(value);
+        return Number.isFinite(temperature) && temperature >= 10 && temperature <= 38;
+    }
+    ensureValidThermostatSetpoints(dev, svc) {
+        const C = this.api.hap.Characteristic;
+        if (!this.isValidTargetTemperature(dev.targetTemp)) {
+            dev.targetTemp = 20;
+            svc.updateCharacteristic(C.TargetTemperature, 20);
+        }
+        if (!this.isValidTargetTemperature(dev.heating)) {
+            dev.heating = 20;
+            svc.updateCharacteristic(C.HeatingThresholdTemperature, 20);
+        }
+        if (!this.isValidTargetTemperature(dev.cooling)) {
+            dev.cooling = 25;
+            svc.updateCharacteristic(C.CoolingThresholdTemperature, 25);
+        }
+    }
+    resolveAutoModeTargetTemperature(dev) {
+        const heating = this.isValidTargetTemperature(dev.heating) ? Number(dev.heating) : undefined;
+        const cooling = this.isValidTargetTemperature(dev.cooling) ? Number(dev.cooling) : undefined;
+        if (heating === undefined && cooling === undefined)
+            return undefined;
+        if (heating === undefined)
+            return cooling;
+        if (cooling === undefined)
+            return heating;
+        const current = this.normalizeCurrentTemperature(dev.temperature);
+        if (current === undefined)
+            return cooling;
+        return current <= heating ? heating : cooling;
+    }
+    logInvalidThermostatValue(key, message) {
+        if (this.invalidThermostatWarnings.has(key)) {
+            return;
+        }
+        this.invalidThermostatWarnings.add(key);
+        this.log.warn(`${message}. Future repeats will be suppressed.`);
+    }
     // Exposed for accessory class
     getInfusion() {
         return this.infusion;

package/dist/platformAccessory.d.ts

@@ -9,4 +9,7 @@ export declare class VantagePlatformAccessory {
     /** Call this both on create and on restore */
     registerServices(): void;
     private safeRemoveCharacteristic;
+    private hapTargetTemperature;
+    private hapHeatingThreshold;
+    private hapCoolingThreshold;
 }