homebridge-nuheat2 1.2.4-beta.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to this project should be documented in this file
+
+## [Unreleased]
+
+## [1.2.4-beta.0] - 2026-04-11
+
+### Changed
+
+- Delay platform startup until Homebridge finishes restoring cached accessories
+- Allow overriding Nuheat OAuth client settings through config or environment variables
+- Improve SignalR reconnection handling and token refresh behavior
+- Add basic regression tests and modernize package metadata for Homebridge 1.8+ and 2.0 betas
+- Publish the maintained fork under the new npm package identity `homebridge-nuheat2`
+
+### Fixed
+
+- Correct manual-mode thermostat mapping so HomeKit no longer snaps back to off
+- Fix thermostat online-state handling so status updates no longer rely on an assignment bug
+- Pin transitive websocket and cookie dependencies away from known vulnerable versions
+
+## [1.2.3] - 2024-11-04
+
+### Fixed
+
+- Bug when using away mode switches
+- Variable handling in some debug logging
+
+## [1.2.2] - 2023-06-13
+
+### Fixed
+
+- variable typo
+
+## [1.2.1] - 2023-06-01
+
+### Fixed
+
+- hold length bug
+
+## [1.2.0] - 2023-05-26
+
+### Changed
+
+- client secret for api auth
+
+### Fixed
+
+- async updates from the api to reduce cookie creation
+
+## [1.1.4] - 2023-05-12
+
+### Changed
+
+- error handling when unable to get access token, as to not crash homebridge
+
+## [1.1.3] - 2023-04-17
+
+### Fixed
+
+- typo in away mode
+
+## [1.1.2] - 2022-12-24
+
+### Fixed
+
+- some unhandled api auth error
+
+### Changed
+
+- some debug logging code
+
+## [1.1.1] - 2022-11-17
+
+### Fixed
+
+- changed the 'homebridge-nuheat' name to be lower case so HOOBS handles properly
+
+## [1.1.0] - 2022-11-15
+
+### Added
+
+- Added `homebridge-ui` support with auto detection
+- Added Away Mode switches for groups
+
+### Changed
+
+- Changed the underlying API to use nuheats new api system

package/README.md

@@ -0,0 +1,120 @@
+# homebridge-nuheat2
+
+[![npm version](https://img.shields.io/npm/v/homebridge-nuheat2.svg)](https://www.npmjs.com/package/homebridge-nuheat2)
+[![npm downloads](https://img.shields.io/npm/dm/homebridge-nuheat2.svg)](https://www.npmjs.com/package/homebridge-nuheat2)
+
+Homebridge platform plugin for Nuheat Signature floor-heating thermostats.
+
+This fork focuses on modernizing the plugin for current Homebridge releases, improving runtime stability, and preparing for Homebridge 2.0 while keeping the existing `NuHeat` platform configuration intact.
+
+## Highlights
+
+- Automatically discovers thermostats on the authenticated Nuheat account
+- Optionally creates HomeKit switches for Nuheat group away mode
+- Supports permanent, scheduled, and timed holds
+- Uses Nuheat's OAuth-based API instead of legacy site scraping
+- Includes compatibility improvements for Homebridge 1.8+ and 2.0 betas
+- Allows advanced OAuth overrides for long-term API stability
+
+## Compatibility
+
+- Homebridge: `^1.8.0 || ^2.0.0-beta.0`
+- Node.js: `^18.20.4 || ^20.18.0 || ^22 || ^24`
+
+For current Homebridge 2.0 betas, use Node 22 or 24.
+
+## Installation
+
+Install Homebridge first:
+
+```bash
+npm install -g homebridge
+```
+
+Then install the plugin:
+
+```bash
+npm install -g homebridge-nuheat2
+```
+
+The published package name for this maintained fork is `homebridge-nuheat2`. The Homebridge platform name in config remains `NuHeat`.
+
+## Configuration
+
+Most users should configure the plugin through Homebridge Config UI X, but the equivalent JSON looks like this:
+
+```json
+{
+  "platform": "NuHeat",
+  "name": "NuHeat",
+  "email": "email@address.com",
+  "password": "password123",
+  "devices": [{ "serialNumber": "1111111" }, { "serialNumber": "2222222" }],
+  "autoPopulateAwayModeSwitches": true,
+  "holdLength": 1440,
+  "refresh": 60
+}
+```
+
+### Options
+
+- `platform`: Must be `NuHeat`
+- `name`: Display name used in Homebridge logs
+- `email`: MyNuheat account email address
+- `password`: MyNuheat account password
+- `devices`: Optional list of thermostats to expose
+- `serialNumber`: Thermostat serial number from MyNuheat
+- `autoPopulateAwayModeSwitches`: Automatically expose switches for all groups on the account
+- `groups`: Optional allow-list of groups to expose as away-mode switches
+- `groupName`: Group name as shown in MyNuheat
+- `holdLength`: Hold duration in minutes
+- `refresh`: Poll interval in seconds, default `60`
+- `debug`: Enables verbose logging
+- `clientId`: Optional advanced override for the Nuheat OAuth client ID
+- `clientSecret`: Optional advanced override for the Nuheat OAuth client secret
+- `redirectUri`: Optional advanced override for the Nuheat OAuth redirect URI, default `http://localhost`
+
+### Hold Length Behavior
+
+- `0`: hold until the next scheduled event
+- `1-1439`: timed hold for the configured number of minutes
+- `1440`: permanent hold
+
+### Device Discovery
+
+If `devices` is omitted or empty, the plugin will automatically expose every thermostat on the authenticated account.
+
+If `groups` is omitted and `autoPopulateAwayModeSwitches` is enabled, the plugin will automatically expose away-mode switches for all groups on the account.
+
+## Nuheat API Access
+
+Nuheat's public OpenAPI documentation indicates that third-party developers should request their own API credentials:
+
+- [Nuheat OpenAPI docs](https://api.mynuheat.com/)
+- [Nuheat API access request page](https://www.nuheat.com/openapi)
+
+This fork still supports the legacy built-in OAuth client settings as a fallback, but using your own `clientId` and `clientSecret` is the recommended long-term path.
+
+## What's New In This Fork
+
+- Fixed the manual-mode thermostat issue where HomeKit could immediately snap back to `Off`
+- Hardened online-state parsing and general accessory refresh behavior
+- Delayed platform startup until Homebridge finishes restoring cached accessories
+- Improved SignalR reconnect handling
+- Added regression tests for the key thermostat behavior fixes
+- Updated package metadata and dependency overrides for a cleaner modern release
+- Published under the maintainer-owned package identity `homebridge-nuheat2`
+
+## Development
+
+Run the test suite with:
+
+```bash
+npm test
+```
+
+## Roadmap
+
+- Validate the plugin against an official Nuheat API client registration
+- Verify group and away-mode behavior against current live API responses
+- Revisit whether SignalR notifications can reduce polling further in real-world deployments

package/config.schema.json

@@ -0,0 +1,101 @@
+{
+  "pluginAlias": "NuHeat",
+  "pluginType": "platform",
+  "singular": false,
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "required": true,
+        "default": "NuHeat"
+      },
+      "email": {
+        "title": "email",
+        "type": "string",
+        "required": true,
+        "format": "email"
+      },
+      "password": {
+        "title": "password",
+        "type": "string",
+        "required": true
+      },
+      "clientId": {
+        "title": "Nuheat Client ID",
+        "type": "string",
+        "description": "Optional advanced override. Leave blank to use the built-in default client ID."
+      },
+      "clientSecret": {
+        "title": "Nuheat Client Secret",
+        "type": "string",
+        "description": "Optional advanced override. Leave blank to use the built-in default client secret."
+      },
+      "redirectUri": {
+        "title": "Nuheat Redirect URI",
+        "type": "string",
+        "description": "Optional advanced override for OAuth redirect URI.",
+        "placeholder": "http://localhost"
+      },
+      "devices": {
+        "title": "Devices",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "serialNumber": {
+              "title": "Serial Number",
+              "type": "string",
+              "required": true
+            },
+            "disabled": {
+              "title": "Disabled",
+              "type": "boolean"
+            }
+          }
+        }
+      },
+      "autoPopulateAwayModeSwitches": {
+        "title": "Auto populate Away Mode switches for all available groups",
+        "type": "boolean"
+      },
+      "groups": {
+        "title": "Groups",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "groupName": {
+              "title": "Group Name",
+              "type": "string",
+              "required": true
+            },
+            "disabled": {
+              "title": "Disabled",
+              "type": "boolean"
+            }
+          }
+        }
+      },
+      "holdLength": {
+        "title": "Hold Length (in minutes)",
+        "type": "integer",
+        "description": "If set to 0, set point changes will hold until the next scheduled event. If set to 1440 (default), set point changes will be permanent. Set to any value in between for a timed hold.",
+        "placeholder": 1440
+      },
+      "refresh": {
+        "title": "Refresh Interval (in seconds)",
+        "type": "integer",
+        "placeholder": 60,
+        "minimum": 1
+      },
+      "debug": {
+        "title": "Enable debug logs",
+        "type": "boolean"
+      }
+    }
+  },
+  "form": null,
+  "display": null
+}

package/index.js

@@ -0,0 +1,360 @@
+"use strict";
+
+let NuHeatAPI = require("./lib/NuHeatAPI.js");
+let NuHeatGroup = require("./lib/NuHeatGroup.js");
+let NuHeatThermostat = require("./lib/NuHeatThermostat.js");
+let NuHeatListener = require("./lib/NuHeatListener.js");
+const logger = require("./lib/logger");
+
+let Homebridge, PlatformAccessory, Service, Characteristic, UUIDGen;
+const PLUGIN_NAME = "homebridge-nuheat2";
+const PLATFORM_NAME = "NuHeat";
+
+module.exports = function (homebridge) {
+  Homebridge = homebridge;
+  PlatformAccessory = homebridge.platformAccessory;
+  Characteristic = homebridge.hap.Characteristic;
+  Service = homebridge.hap.Service;
+  UUIDGen = homebridge.hap.uuid;
+
+  homebridge.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, NuHeatPlatform, true);
+};
+
+class NuHeatPlatform {
+  constructor(log, config, api) {
+    if (!config) {
+      log.warn("Ignoring NuHeat Platform setup because it is not configured");
+      this.disabled = true;
+      return;
+    }
+
+    if ((!config.Email && !config.email) || !config.password) {
+      log.warn(
+        "Ignoring NuHeat Platform setup because it is not configured properly. Missing email or password",
+      );
+      this.disabled = true;
+      return;
+    }
+
+    this.config = config;
+    this.config.email = this.config.Email || this.config.email;
+    this.config.holdLength = Math.min(
+      1440,
+      Math.max(0, this.config.holdLength || 1440),
+    );
+    this.api = api;
+    this.accessories = [];
+    this.log = new logger.Logger(log, this.config.debug || false);
+    this.refreshTimer = null;
+    this.didFinishLaunching = false;
+
+    if (this.api?.on) {
+      // Modern Homebridge startup restores cached accessories first, then calls didFinishLaunching.
+      this.api.on("didFinishLaunching", async () => {
+        this.didFinishLaunching = true;
+        await this.setupPlatform();
+      });
+      this.api.on("shutdown", () => {
+        this.teardown();
+      });
+    } else {
+      this.setupPlatform();
+    }
+  }
+
+  configureAccessory(accessory) {
+    this.accessories.push({ uuid: accessory.UUID, accessory });
+  }
+
+  async setupPlatform() {
+    if (this.disabled) {
+      return;
+    }
+
+    if (this.api?.on && !this.didFinishLaunching) {
+      return;
+    }
+
+    this.log.info("Logging into NuHeat...");
+    this.NuHeatAPI = new NuHeatAPI(
+      this.config.email,
+      this.config.password,
+      this.log,
+      {
+        clientId: this.config.clientId,
+        clientSecret: this.config.clientSecret,
+        redirectUri: this.config.redirectUri,
+      },
+    );
+
+    if (await this.NuHeatAPI.returnAccessToken()) {
+      await this.setupGroups();
+      await this.setupThermostats();
+      this.cleanupRemovedAccessories();
+
+      if (this.refreshTimer) {
+        clearInterval(this.refreshTimer);
+      }
+
+      this.refreshTimer = setInterval(
+        this.refreshAccessories.bind(this),
+        (this.config.refresh || 60) * 1000,
+      );
+
+      if (!this.NuHeatListener) {
+        this.NuHeatListener = new NuHeatListener(this.NuHeatAPI, this);
+        this.NuHeatListener.connect();
+      }
+    } else {
+      this.log.error(
+        "Unable to acquire an access token. We will try again later.",
+      );
+      setTimeout(
+        this.setupPlatform.bind(this),
+        (this.config.refresh || 60) * 1000,
+      );
+    }
+  }
+
+  async setupGroups() {
+    const groupArray = this.config.groups || [];
+    if (!(this.config.autoPopulateAwayModeSwitches || groupArray.length > 0)) {
+      return;
+    }
+
+    const response = await this.NuHeatAPI.refreshGroups();
+    if (!response) {
+      this.log.error("Error getting data from NuHeatAPI");
+      return;
+    }
+
+    if (groupArray.length === 0) {
+      this.log.info(
+        "No groups defined in config. Auto populating away mode switches by pulling all groups from the account.",
+      );
+    }
+
+    await Promise.all(
+      response.map((deviceData) => {
+        if (
+          !(
+            groupArray.length === 0 ||
+            groupArray.find(
+              (device) =>
+                device.groupName == deviceData.groupName && !device.disabled,
+            )
+          )
+        ) {
+          return;
+        }
+
+        const uuid = UUIDGen.generate(deviceData.groupId.toString());
+        let deviceAccessory = false;
+
+        if (this.accessories.find((accessory) => accessory.uuid === uuid)) {
+          deviceAccessory = this.accessories.find(
+            (accessory) => accessory.uuid === uuid,
+          ).accessory;
+        }
+
+        if (!deviceAccessory) {
+          this.log.info("Creating new away mode switch", deviceData.groupName);
+          const accessory = new PlatformAccessory(deviceData.groupName, uuid);
+          accessory.addService(
+            Service.Switch,
+            deviceData.groupName + " Away Mode",
+          );
+          this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [
+            accessory,
+          ]);
+          deviceAccessory = accessory;
+          this.accessories.push({ uuid });
+        }
+
+        this.accessories.find(
+          (accessory) => accessory.uuid === uuid,
+        ).accessory = new NuHeatGroup(
+          this.log,
+          deviceData,
+          deviceAccessory instanceof NuHeatGroup
+            ? deviceAccessory.accessory
+            : deviceAccessory,
+          this.NuHeatAPI,
+          Homebridge,
+        );
+        this.accessories.find(
+          (accessory) => accessory.uuid === uuid,
+        ).existsInConfig = true;
+        this.log.info("Loaded away mode switch", deviceData.groupName);
+        this.accessories
+          .find((accessory) => accessory.uuid === uuid)
+          .accessory.updateValues(deviceData);
+      }),
+    );
+  }
+
+  async setupThermostats() {
+    const deviceArray = this.config.devices || [];
+    const response = await this.NuHeatAPI.refreshThermostats();
+
+    if (!response) {
+      this.log.error("Error getting data from NuHeatAPI");
+      return;
+    }
+
+    if (deviceArray.length === 0) {
+      this.log.info(
+        "No devices defined in config. Auto populating thermostats by pulling everything from the account.",
+      );
+    }
+
+    await Promise.all(
+      response.map((deviceData) => {
+        if (
+          !(
+            deviceArray.length === 0 ||
+            deviceArray.find(
+              (device) =>
+                device.serialNumber == deviceData.serialNumber &&
+                !device.disabled,
+            )
+          )
+        ) {
+          return;
+        }
+
+        const uuid = UUIDGen.generate(deviceData.serialNumber.toString());
+        let deviceAccessory = false;
+
+        if (this.accessories.find((accessory) => accessory.uuid === uuid)) {
+          deviceAccessory = this.accessories.find(
+            (accessory) => accessory.uuid === uuid,
+          ).accessory;
+        }
+
+        if (!deviceAccessory) {
+          this.log.info(
+            "Creating new thermostat for serial number: " +
+              deviceData.serialNumber,
+          );
+          const accessory = new PlatformAccessory(deviceData.name, uuid);
+          accessory.addService(Service.Thermostat, deviceData.name);
+          this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [
+            accessory,
+          ]);
+          deviceAccessory = accessory;
+          this.accessories.push({ uuid });
+        }
+
+        this.accessories.find(
+          (accessory) => accessory.uuid === uuid,
+        ).accessory = new NuHeatThermostat(
+          this.log,
+          deviceData,
+          this.config.holdLength,
+          deviceAccessory instanceof NuHeatThermostat
+            ? deviceAccessory.accessory
+            : deviceAccessory,
+          this.NuHeatAPI,
+          Homebridge,
+        );
+        this.accessories.find(
+          (accessory) => accessory.uuid === uuid,
+        ).existsInConfig = true;
+        this.log.info(
+          "Loaded thermostat " +
+            deviceData.serialNumber +
+            " " +
+            deviceData.name,
+        );
+        this.accessories
+          .find((accessory) => accessory.uuid === uuid)
+          .accessory.updateValues(deviceData);
+      }),
+    );
+  }
+
+  cleanupRemovedAccessories() {
+    this.accessories.forEach(function (thisAccessory) {
+      if (thisAccessory.existsInConfig !== true) {
+        try {
+          this.log.info(
+            "Deleting removed accessory",
+            thisAccessory.accessory
+              .getService(Service.AccessoryInformation)
+              .getCharacteristic(Characteristic.Name)
+              .getValue(),
+          );
+        } catch {
+          this.log.info("Deleting removed accessory");
+        }
+
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [
+          thisAccessory.accessory,
+        ]);
+      }
+    }, this);
+  }
+
+  async refreshAccessories() {
+    await this.refreshGroups();
+    await this.refreshThermostats();
+  }
+
+  async refreshGroups() {
+    this.log.debug("Trying to refresh groups.");
+    const response = await this.NuHeatAPI.refreshGroups();
+
+    if (!response) {
+      this.log.error("Error getting data from NuHeatAPI in group refresh");
+      return false;
+    }
+
+    response.forEach(function (deviceData) {
+      const thisAccessory = this.accessories.find(
+        (accessory) =>
+          accessory.uuid === UUIDGen.generate(deviceData.groupId.toString()),
+      );
+      if (thisAccessory) {
+        thisAccessory.accessory.updateValues(deviceData);
+      }
+    }, this);
+
+    return true;
+  }
+
+  async refreshThermostats() {
+    this.log.debug("Trying to refresh thermostats.");
+    const response = await this.NuHeatAPI.refreshThermostats();
+
+    if (!response) {
+      this.log.error("Error getting data from NuHeatAPI in thermostat refresh");
+      return false;
+    }
+
+    response.forEach(function (deviceData) {
+      const thisAccessory = this.accessories.find(
+        (accessory) =>
+          accessory.uuid ===
+          UUIDGen.generate(deviceData.serialNumber.toString()),
+      );
+      if (thisAccessory) {
+        thisAccessory.accessory.updateValues(deviceData);
+      }
+    }, this);
+
+    return true;
+  }
+
+  teardown() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+
+    if (this.NuHeatListener) {
+      this.NuHeatListener.disconnect();
+      this.NuHeatListener = null;
+    }
+  }
+}