homebridge-nuheat2 1.2.10 → 1.2.12

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project should be documented in this file
 
 ## [Unreleased]
 
+## [1.2.12] - 2026-04-21
+
+### Fixed
+
+- Treat Nuheat thermostats as heat-only in HomeKit so the target mode no longer advertises a misleading off option
+- Translate any incoming HomeKit off request into the minimum Nuheat setpoint instead of bouncing back after refresh
+- Apply the Nuheat account temperature scale to the thermostat display-units characteristic so HomeKit shows the correct hardware display unit
+- Coalesce and briefly de-duplicate repeated SignalR thermostat and group notifications to reduce redundant full refreshes and log noise
+
+## [1.2.11] - 2026-04-21
+
+### Fixed
+
+- Relax the optional `devices` and `groups` array item schema so Homebridge Config UI no longer shows validation errors for blank rows
+- Ignore blank `devices` rows at runtime so they do not interfere with thermostat auto-discovery
+
 ## [1.2.10] - 2026-04-21
 
 ### Added

package/README.md

@@ -67,11 +67,11 @@ Most users should configure the plugin through Homebridge Config UI X, but the e
 - `email`: MyNuheat account email address
 - `Email`: Legacy alias still accepted for backward compatibility, but `email` is the preferred documented field
 - `password`: MyNuheat account password
-- `devices`: Optional list of thermostats to expose. If omitted or empty, every thermostat on the account will be discovered automatically
+- `devices`: Optional list of thermostats to expose. If omitted or empty, every thermostat on the account will be discovered automatically. Blank rows in the UI are ignored
 - `serialNumber`: Thermostat serial number from MyNuheat
 - `autoPopulateAwayModeSwitches`: Automatically expose away-mode switches for all groups on the account
 - `exposeScheduleSwitches`: Optionally expose a switch per thermostat that reflects whether the thermostat is following its schedule and can be turned on to resume the schedule
-- `groups`: Optional allow-list of groups to expose as away-mode switches. This only affects group/away-mode accessories
+- `groups`: Optional allow-list of groups to expose as away-mode switches. This only affects group/away-mode accessories. Blank rows in the UI are ignored
 - `groupName`: Group name as shown in MyNuheat
 - `holdLength`: Hold duration in minutes
 - `refresh`: Poll interval in seconds, default `60`
@@ -138,10 +138,12 @@ npm test
 GitHub Actions now handles two jobs for this repository:
 
 - `.github/workflows/ci.yml` runs `npm ci`, `npm run typecheck`, and `npm test` on pushes and pull requests across Node 20, 22, and 24
-- `.github/workflows/publish.yml` runs on pushes to `master` when `package.json` changes, re-runs the checks on Node 24, and publishes to npm only when the `package.json` version is not already on the registry
+- `.github/workflows/publish.yml` runs on pushes to `master` when `package.json` changes, re-runs the checks on Node 24, publishes to npm only when the `package.json` version is not already on the registry, and creates or updates the matching GitHub Release
 
 The publish workflow also maps prerelease versions to npm dist-tags automatically. For example, `1.2.7-beta.1` publishes with the `beta` tag, while stable versions publish to `latest`.
 
+Release notes are expected in `docs/release-notes/<version>.md`. The publish workflow will fail if that file is missing for the version in `package.json`, which makes the GitHub Release step part of the normal release checklist instead of a manual follow-up.
+
 ### Recommended npm Setup
 
 Use npm trusted publishing rather than a long-lived automation token.

package/config.schema.json

@@ -43,11 +43,9 @@
       "devices": {
         "title": "Devices",
         "type": "array",
+        "description": "Optional allow-list of thermostats to expose. Leave empty to auto-discover all thermostats on the account.",
         "items": {
           "type": "object",
-          "required": [
-            "serialNumber"
-          ],
           "properties": {
             "serialNumber": {
               "title": "Serial Number",
@@ -72,11 +70,9 @@
       "groups": {
         "title": "Groups",
         "type": "array",
+        "description": "Optional allow-list of groups to expose as away-mode switches. Leave empty unless you want to add specific groups manually.",
         "items": {
           "type": "object",
-          "required": [
-            "groupName"
-          ],
           "properties": {
             "groupName": {
               "title": "Group Name",

package/index.js

@@ -74,6 +74,11 @@ class NuHeatPlatform {
             typeof group.groupName === "string" &&
             group.groupName.trim().length > 0);
     }
+    getConfiguredDevices() {
+        return (this.config.devices || []).filter((device) => !!device &&
+            typeof device.serialNumber === "string" &&
+            device.serialNumber.trim().length > 0);
+    }
     shouldManageGroups() {
         return (!!this.config.autoPopulateAwayModeSwitches ||
             this.getConfiguredGroups().length > 0);
@@ -154,7 +159,7 @@ class NuHeatPlatform {
         }));
     }
     async setupThermostats() {
-        const deviceArray = this.config.devices || [];
+        const deviceArray = this.getConfiguredDevices();
         const response = await this.NuHeatAPI.refreshThermostats();
         if (!response || !Array.isArray(response)) {
             this.log.error("Error getting data from NuHeatAPI");
@@ -184,7 +189,7 @@ class NuHeatPlatform {
                 entry = { uuid };
                 this.accessories.push(entry);
             }
-            entry.accessory = new NuHeatThermostat(this.log, deviceData, this.config.holdLength || 1440, getPlatformAccessory(deviceAccessory), this.NuHeatAPI, Homebridge);
+            entry.accessory = new NuHeatThermostat(this.log, deviceData, this.config.holdLength || 1440, getPlatformAccessory(deviceAccessory), this.NuHeatAPI, Homebridge, this.account?.temperatureScale);
             entry.existsInConfig = true;
             this.log.info("Loaded thermostat " +
                 deviceData.serialNumber +

package/lib/NuHeatListener.js

@@ -1,16 +1,19 @@
 "use strict";
 const signalR = require("@microsoft/signalr");
+const NOTIFICATION_DEDUPE_WINDOW_MS = 2000;
 class NuHeatListener {
     nuHeatAPI;
     nuHeatPlatform;
     log;
     notificationTypes;
     connection;
+    recentNotifications;
     constructor(nuHeatAPI, nuheatPlatform) {
         this.nuHeatAPI = nuHeatAPI;
         this.nuHeatPlatform = nuheatPlatform;
         this.log = nuheatPlatform.log;
         this.notificationTypes = ["2", "4"];
+        this.recentNotifications = new Map();
         this.connection = new signalR.HubConnectionBuilder()
             .withUrl("https://api.mynuheat.com/notificationsHost", {
             accessTokenFactory: async () => {
@@ -73,8 +76,10 @@ class NuHeatListener {
         });
     }
     traceNotification(notificationList) {
+        let shouldRefreshThermostats = false;
+        let shouldRefreshGroups = false;
         notificationList.forEach((notification) => {
-            let notificationType = "";
+            let notificationType = "Unknown";
             switch (notification.type) {
                 case 0:
                 case 1:
@@ -82,15 +87,15 @@ class NuHeatListener {
                     break;
                 case 2:
                     notificationType = "Thermostat";
-                    void this.nuHeatPlatform.refreshThermostats();
+                    shouldRefreshThermostats = shouldRefreshThermostats || !this.isDuplicateNotification(notification);
                     break;
                 case 3:
                     notificationType = "Schedule";
-                    void this.nuHeatPlatform.refreshThermostats();
+                    shouldRefreshThermostats = shouldRefreshThermostats || !this.isDuplicateNotification(notification);
                     break;
                 case 4:
                     notificationType = "Group";
-                    void this.nuHeatPlatform.refreshGroups();
+                    shouldRefreshGroups = shouldRefreshGroups || !this.isDuplicateNotification(notification);
                     break;
             }
             this.log.debug(notificationType +
@@ -98,10 +103,38 @@ class NuHeatListener {
                 notification.id +
                 " at " +
                 notification.timeStamp +
-                ". Refreshing data for all " +
-                notificationType +
-                "s");
+                ".");
         });
+        if (shouldRefreshThermostats) {
+            void this.nuHeatPlatform.refreshThermostats();
+        }
+        if (shouldRefreshGroups) {
+            void this.nuHeatPlatform.refreshGroups();
+        }
+    }
+    isDuplicateNotification(notification) {
+        const key = String(notification.type) +
+            ":" +
+            String(notification.id) +
+            ":" +
+            notification.timeStamp;
+        const now = Date.now();
+        this.cleanupRecentNotifications(now);
+        const lastSeenAt = this.recentNotifications.get(key);
+        if (lastSeenAt !== undefined &&
+            now - lastSeenAt < NOTIFICATION_DEDUPE_WINDOW_MS) {
+            this.log.debug("Ignoring duplicate notification " + key + ".");
+            return true;
+        }
+        this.recentNotifications.set(key, now);
+        return false;
+    }
+    cleanupRecentNotifications(now) {
+        for (const [key, seenAt] of this.recentNotifications.entries()) {
+            if (now - seenAt >= NOTIFICATION_DEDUPE_WINDOW_MS) {
+                this.recentNotifications.delete(key);
+            }
+        }
     }
 }
 module.exports = NuHeatListener;

package/lib/NuHeatThermostat.js

@@ -2,13 +2,16 @@
 const NuHeatModels_1 = require("./NuHeatModels");
 let Characteristic;
 let ThermostatService;
+const MIN_TARGET_TEMPERATURE_C = 10;
+const MAX_TARGET_TEMPERATURE_C = 38;
 class NuHeatThermostat {
     log;
     deviceData;
     holdLength;
     accessory;
     NuHeatAPI;
-    constructor(log, deviceData, holdLength, accessory, NuHeatAPI, homebridge) {
+    temperatureScale;
+    constructor(log, deviceData, holdLength, accessory, NuHeatAPI, homebridge, temperatureScale) {
         Characteristic = homebridge.hap.Characteristic;
         ThermostatService = homebridge.hap.Service.Thermostat;
         this.log = log;
@@ -16,6 +19,7 @@ class NuHeatThermostat {
         this.holdLength = holdLength;
         this.accessory = accessory;
         this.NuHeatAPI = NuHeatAPI;
+        this.temperatureScale = temperatureScale;
         this.accessory
             .getService(homebridge.hap.Service.AccessoryInformation)
             .setCharacteristic(Characteristic.Manufacturer, "NuHeat")
@@ -25,39 +29,48 @@ class NuHeatThermostat {
         this.setupListeners();
     }
     setupListeners() {
+        const thermostatService = this.accessory.getService(ThermostatService);
         this.log.info("holdLength: " + this.holdLength, this.deviceData.name);
-        this.accessory
-            .getService(ThermostatService)
+        thermostatService
             .getCharacteristic(Characteristic.TargetHeatingCoolingState)
             .setProps({
-            validValues: [0, 1],
+            validValues: [Characteristic.TargetHeatingCoolingState.HEAT],
         })
             .on("set", this.setTargetHeatingCooling.bind(this));
-        this.accessory
-            .getService(ThermostatService)
-            .getCharacteristic(Characteristic.CurrentTemperature)
-            .setProps({
+        thermostatService.getCharacteristic(Characteristic.CurrentTemperature).setProps({
             minValue: -100,
             maxValue: 100,
         });
-        this.accessory
-            .getService(ThermostatService)
+        thermostatService
             .getCharacteristic(Characteristic.TargetTemperature)
             .setProps({
             minStep: 0.5,
         })
             .on("set", this.setTargetTemperature.bind(this));
+        this.updateTemperatureDisplayUnits();
     }
-    setTargetHeatingCooling(_value, callback) {
+    async setTargetHeatingCooling(value, callback) {
+        if (value !== Characteristic.TargetHeatingCoolingState.OFF) {
+            callback(null);
+            void this.updateAccessory();
+            return;
+        }
+        this.log.info("NuHeat does not support an off mode. Setting the thermostat to its minimum target temperature instead.", this.deviceData.name);
+        const response = await this.NuHeatAPI.setHeatSetpoint(this.deviceData.serialNumber ?? "", this.toNuHeatTemperature(MIN_TARGET_TEMPERATURE_C), this.holdLength);
+        if (!response) {
+            this.log.error("Error setting minimum target temperature for off request", this.deviceData.name);
+            callback(new Error("Error: setTargetHeatingCooling"));
+            return;
+        }
+        this.updateValues(response);
         callback(null);
-        void this.updateAccessory();
     }
     async setTargetTemperature(value, callback) {
-        this.log.info("Setting target temperature to " + value + "°C", this.deviceData.name);
-        if (value < 10)
-            value = 10;
-        if (value > 38)
-            value = 38;
+        this.log.info("Setting target temperature to " + value + " C", this.deviceData.name);
+        if (value < MIN_TARGET_TEMPERATURE_C)
+            value = MIN_TARGET_TEMPERATURE_C;
+        if (value > MAX_TARGET_TEMPERATURE_C)
+            value = MAX_TARGET_TEMPERATURE_C;
         const heatSetPoint = this.toNuHeatTemperature(value);
         this.log.debug("setTargetTemperature " + heatSetPoint, this.deviceData.name);
         const response = await this.NuHeatAPI.setHeatSetpoint(this.deviceData.serialNumber ?? "", heatSetPoint, this.holdLength);
@@ -81,25 +94,29 @@ class NuHeatThermostat {
     }
     updateValues(newValues) {
         if (this.isOnline(newValues)) {
+            this.updateTemperatureDisplayUnits();
             let currentTemperature = Number(this.toHBTemperature(newValues.currentTemperature ?? 0));
-            this.log.debug("Current temperature is " + currentTemperature + "°C", this.deviceData.name);
+            this.log.debug("Current temperature is " + currentTemperature + " C", this.deviceData.name);
             this.accessory
                 .getService(ThermostatService)
                 .getCharacteristic(Characteristic.CurrentTemperature)
                 .updateValue(currentTemperature);
             let setPointTemperature = Number(this.toHBTemperature(newValues.setPointTemp ?? 0));
-            if (setPointTemperature < 10)
-                setPointTemperature = 10;
-            if (setPointTemperature > 38)
-                setPointTemperature = 38;
-            this.log.debug("Setpoint temperature is " + setPointTemperature + "°C", this.deviceData.name);
+            if (setPointTemperature < MIN_TARGET_TEMPERATURE_C) {
+                setPointTemperature = MIN_TARGET_TEMPERATURE_C;
+            }
+            if (setPointTemperature > MAX_TARGET_TEMPERATURE_C) {
+                setPointTemperature = MAX_TARGET_TEMPERATURE_C;
+            }
+            this.log.debug("Setpoint temperature is " + setPointTemperature + " C", this.deviceData.name);
             this.accessory
                 .getService(ThermostatService)
                 .getCharacteristic(Characteristic.TargetTemperature)
                 .updateValue(setPointTemperature);
-            let currentHeatingCoolingState = 0;
+            let currentHeatingCoolingState = Characteristic.CurrentHeatingCoolingState.OFF;
             if (newValues.isHeating) {
-                currentHeatingCoolingState = 1;
+                currentHeatingCoolingState =
+                    Characteristic.CurrentHeatingCoolingState.HEAT;
             }
             this.log.debug("Current heating state is " + currentHeatingCoolingState, this.deviceData.name);
             this.accessory
@@ -153,5 +170,29 @@ class NuHeatThermostat {
         }
         return true;
     }
+    updateTemperatureDisplayUnits() {
+        const displayUnits = this.toHomeKitDisplayUnits(this.temperatureScale);
+        if (displayUnits === undefined ||
+            !Characteristic.TemperatureDisplayUnits) {
+            return;
+        }
+        this.accessory
+            .getService(ThermostatService)
+            .getCharacteristic(Characteristic.TemperatureDisplayUnits)
+            .updateValue(displayUnits);
+    }
+    toHomeKitDisplayUnits(temperatureScale) {
+        if (!temperatureScale || !Characteristic.TemperatureDisplayUnits) {
+            return undefined;
+        }
+        const normalizedScale = temperatureScale.trim().toLowerCase();
+        if (normalizedScale.startsWith("f")) {
+            return Characteristic.TemperatureDisplayUnits.FAHRENHEIT;
+        }
+        if (normalizedScale.startsWith("c")) {
+            return Characteristic.TemperatureDisplayUnits.CELSIUS;
+        }
+        return undefined;
+    }
 }
 module.exports = NuHeatThermostat;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-nuheat2",
-  "version": "1.2.10",
+  "version": "1.2.12",
   "description": "Homebridge Platform for NuHeat Signature Thermostats",
   "main": "index.js",
   "scripts": {