homebridge-nuheat2 1.2.11 → 1.2.13

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project should be documented in this file
 
 ## [Unreleased]
 
+## [1.2.13] - 2026-04-24
+
+### Changed
+
+- Subscribe to Nuheat schedule notifications alongside thermostat and group notifications
+- Remove an unused Homebridge UI utility dependency from the published package
+- Improve Homebridge Config UI labels, defaults, grouping, and sensitive-field handling
+- Add a custom Homebridge admin UI aligned with the shared Roborock design system
+- Document the upcoming PKCE public-client direction for Nuheat OAuth credentials
+- Enforce a 30-second minimum polling interval at runtime to reduce accidental API load
+
+### Fixed
+
+- Correct refresh-token rotation debug logging so it compares against the previous token
+- Keep notification de-duplication bookkeeping consistent across mixed notification batches
+
+## [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

package/README.md

@@ -44,7 +44,13 @@ The published package name for this maintained fork is `homebridge-nuheat2`. The
 
 ## Configuration
 
-Most users should configure the plugin through Homebridge Config UI X, but the equivalent JSON looks like this:
+Most users should configure the plugin through the custom Homebridge admin UI. It is organized into Account, Accessories, Behavior, Advanced OAuth, and Diagnostics panels and writes the same config keys shown below.
+
+Sensitive values are handled deliberately: saved passwords and legacy client secrets are not redisplayed in the UI. Leave those fields blank to keep the saved value, enter a new value to replace it, or use the Clear Overrides button in Advanced OAuth to remove OAuth overrides.
+
+The Diagnostics panel summarizes the saved configuration and exposure strategy before restart. It does not make live Nuheat API calls.
+
+The equivalent JSON looks like this:
 
 ```json
 {
@@ -52,9 +58,14 @@ Most users should configure the plugin through Homebridge Config UI X, but the e
   "name": "NuHeat",
   "email": "email@address.com",
   "password": "password123",
-  "devices": [{ "serialNumber": "1111111" }, { "serialNumber": "2222222" }],
+  "devices": [
+    { "serialNumber": "1111111", "disabled": false },
+    { "serialNumber": "2222222", "disabled": false }
+  ],
   "autoPopulateAwayModeSwitches": true,
+  "groups": [{ "groupName": "Main Floor", "disabled": false }],
   "exposeScheduleSwitches": false,
+  "enableNotifications": true,
   "holdLength": 1440,
   "refresh": 60
 }
@@ -69,15 +80,17 @@ Most users should configure the plugin through Homebridge Config UI X, but the e
 - `password`: MyNuheat account password
 - `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
+- `disabled`: Available on `devices` and `groups` rows. Keeps the row saved while preventing that thermostat or group from being exposed
 - `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. 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`
-- `debug`: Enables verbose logging
-- `clientId`: Optional advanced override for the Nuheat OAuth client ID. This is recommended once you have official Nuheat API credentials
-- `clientSecret`: Optional advanced override for the Nuheat OAuth client secret
+- `holdLength`: Hold duration in minutes, default `1440`. Values are clamped from `0` to `1440`
+- `refresh`: Poll interval in seconds, default `60`. Values lower than `30` are raised to `30` to reduce API traffic
+- `enableNotifications`: Enables Nuheat SignalR notifications for faster updates. Defaults to `true`; set to `false` only while troubleshooting
+- `debug`: Enables verbose Nuheat API, notification, and accessory logging. Defaults to `false`
+- `clientId`: Optional advanced override for the Nuheat OAuth client ID. Current releases require this to be paired with `clientSecret`; PKCE public-client support is planned but is not active yet
+- `clientSecret`: Optional legacy OAuth client secret override for confidential-client credentials. Required with a custom `clientId` until PKCE support ships. Do not publish or share this value
 - `redirectUri`: Optional advanced override for the Nuheat OAuth redirect URI, default `http://localhost`
 
 ### Hold Length Behavior
@@ -101,7 +114,7 @@ Nuheat's public OpenAPI documentation indicates that third-party developers shou
 - [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 once Nuheat issues them for your integration.
+This fork still supports the legacy built-in OAuth client settings as a fallback. Nuheat is expected to issue a PKCE-based public client for this integration so the plugin can eventually ship with a public `clientId` without distributing a client secret. Until that migration is complete, keep any issued `clientSecret` out of GitHub, npm, screenshots, and shared logs.
 
 ## What's New In This Fork
 
@@ -161,5 +174,6 @@ After that, bump the version in `package.json`, push to `master`, and GitHub Act
 ## Future Work
 
 - Validate the plugin against the official Nuheat API credentials requested for this integration.
+- Move the normal OAuth path to Nuheat's PKCE-based public client once the new client details are issued.
 - Verify group and away-mode behavior against current live API responses.
 - Evaluate whether SignalR notifications can reduce polling further in real-world deployments.

package/config.schema.json

@@ -2,6 +2,10 @@
   "pluginAlias": "NuHeat",
   "pluginType": "platform",
   "singular": false,
+  "customUi": true,
+  "customUiPath": "./homebridge-ui",
+  "headerDisplay": "Connect Nuheat Signature floor-heating thermostats to HomeKit. Most users only need their MyNuheat account email and password.",
+  "footerDisplay": "The npm package is homebridge-nuheat2, but the Homebridge platform remains NuHeat for backward compatibility.",
   "schema": {
     "type": "object",
     "required": [
@@ -10,104 +14,177 @@
       "password"
     ],
     "properties": {
+      "platform": {
+        "title": "Platform",
+        "type": "string",
+        "default": "NuHeat",
+        "const": "NuHeat",
+        "description": "Homebridge platform identifier. Keep this set to NuHeat."
+      },
       "name": {
-        "title": "Name",
+        "title": "Platform Name",
         "type": "string",
-        "default": "NuHeat"
+        "default": "NuHeat",
+        "description": "Display name used for this platform instance in Homebridge logs."
       },
       "email": {
-        "title": "email",
+        "title": "MyNuheat Email",
         "type": "string",
-        "format": "email"
+        "format": "email",
+        "description": "Email address for the MyNuheat account that owns the thermostats."
       },
       "password": {
-        "title": "password",
-        "type": "string"
-      },
-      "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",
+        "title": "MyNuheat Password",
         "type": "string",
-        "description": "Optional advanced override for OAuth redirect URI.",
-        "placeholder": "http://localhost"
+        "format": "password",
+        "description": "Password for the MyNuheat account."
       },
       "devices": {
-        "title": "Devices",
+        "title": "Thermostat Allow-List",
         "type": "array",
-        "description": "Optional allow-list of thermostats to expose. Leave empty to auto-discover all thermostats on the account.",
+        "default": [],
+        "description": "Optional. Leave empty to expose every thermostat on the account. Add rows only if you want to limit HomeKit to specific thermostat serial numbers.",
         "items": {
           "type": "object",
           "properties": {
             "serialNumber": {
               "title": "Serial Number",
-              "type": "string"
+              "type": "string",
+              "description": "Thermostat serial number from MyNuheat."
             },
             "disabled": {
               "title": "Disabled",
-              "type": "boolean"
+              "type": "boolean",
+              "default": false,
+              "description": "Keep this row in the config but do not expose this thermostat."
             }
           }
         }
       },
-      "autoPopulateAwayModeSwitches": {
-        "title": "Auto populate Away Mode switches for all available groups",
-        "type": "boolean"
-      },
-      "exposeScheduleSwitches": {
-        "title": "Expose per-thermostat schedule switches",
-        "type": "boolean",
-        "description": "Creates a switch for each thermostat that reflects whether its schedule is active and can be turned on to resume the configured schedule."
-      },
       "groups": {
-        "title": "Groups",
+        "title": "Away Mode Group Allow-List",
         "type": "array",
-        "description": "Optional allow-list of groups to expose as away-mode switches. Leave empty unless you want to add specific groups manually.",
+        "default": [],
+        "description": "Optional. Leave empty unless you want specific Nuheat groups exposed as away-mode switches.",
         "items": {
           "type": "object",
           "properties": {
             "groupName": {
               "title": "Group Name",
-              "type": "string"
+              "type": "string",
+              "description": "Group name exactly as shown in MyNuheat."
             },
             "disabled": {
               "title": "Disabled",
-              "type": "boolean"
+              "type": "boolean",
+              "default": false,
+              "description": "Keep this row in the config but do not expose this group."
             }
           }
         }
       },
+      "autoPopulateAwayModeSwitches": {
+        "title": "Expose Away Mode Switches For All Groups",
+        "type": "boolean",
+        "default": false,
+        "description": "Automatically create HomeKit away-mode switches for every Nuheat group on the account."
+      },
+      "exposeScheduleSwitches": {
+        "title": "Expose Schedule Switches",
+        "type": "boolean",
+        "default": false,
+        "description": "Create one switch per thermostat. The switch is on when the thermostat follows its Nuheat schedule and can be turned on to resume the schedule."
+      },
       "holdLength": {
-        "title": "Hold Length (in minutes)",
+        "title": "Hold Length (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
+        "default": 1440,
+        "minimum": 0,
+        "maximum": 1440,
+        "description": "Duration for HomeKit setpoint changes. Use 0 to hold until the next scheduled event, 1-1439 for a timed hold, or 1440 for a permanent hold."
       },
       "refresh": {
-        "title": "Refresh Interval (in seconds)",
+        "title": "Polling Interval (seconds)",
         "type": "integer",
-        "placeholder": 60,
-        "minimum": 1
-      },
-      "debug": {
-        "title": "Enable debug logs",
-        "type": "boolean"
+        "default": 60,
+        "minimum": 30,
+        "description": "How often to poll Nuheat as a safety net. Notifications update faster when enabled; avoid very low values to reduce API traffic."
       },
       "enableNotifications": {
-        "title": "Enable Nuheat notifications (SignalR)",
+        "title": "Enable Nuheat Notifications",
         "type": "boolean",
-        "description": "Disable this to use REST polling only while troubleshooting notification or API issues."
+        "default": true,
+        "description": "Use Nuheat SignalR notifications for faster updates. Disable only while troubleshooting, which leaves polling as the fallback."
+      },
+      "debug": {
+        "title": "Enable Debug Logs",
+        "type": "boolean",
+        "default": false,
+        "description": "Write detailed Nuheat API and accessory activity to the Homebridge log."
+      },
+      "clientId": {
+        "title": "Nuheat Client ID",
+        "type": "string",
+        "description": "Advanced OAuth override. Current releases require this to be paired with a clientSecret; PKCE public-client support is planned but not active yet."
+      },
+      "clientSecret": {
+        "title": "Nuheat Client Secret (Legacy)",
+        "type": "string",
+        "format": "password",
+        "description": "Advanced OAuth override for confidential-client credentials. Required with a custom clientId until PKCE support ships. Do not publish or share this value."
+      },
+      "redirectUri": {
+        "title": "Nuheat Redirect URI",
+        "type": "string",
+        "default": "http://localhost",
+        "description": "Advanced OAuth redirect URI. The default is http://localhost."
       }
     }
   },
+  "layout": [
+    "platform",
+    "name",
+    "email",
+    "password",
+    {
+      "type": "fieldset",
+      "title": "Accessories",
+      "expandable": true,
+      "expanded": false,
+      "description": "Control which Nuheat thermostats and group switches appear in HomeKit.",
+      "items": [
+        "devices",
+        "autoPopulateAwayModeSwitches",
+        "groups",
+        "exposeScheduleSwitches"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Behavior",
+      "expandable": true,
+      "expanded": false,
+      "description": "Tune holds, refresh behavior, notifications, and logging.",
+      "items": [
+        "holdLength",
+        "refresh",
+        "enableNotifications",
+        "debug"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced OAuth",
+      "expandable": true,
+      "expanded": false,
+      "description": "Only change these fields when testing Nuheat-issued API credentials.",
+      "items": [
+        "clientId",
+        "clientSecret",
+        "redirectUri"
+      ]
+    }
+  ],
   "form": null,
   "display": null
 }

package/homebridge-ui/public/index.html

@@ -0,0 +1,244 @@
+<link rel="stylesheet" href="styles.css" />
+
+<main class="container">
+  <header>
+    <h1>Nuheat Radiant Floor Heating</h1>
+    <p class="subtitle">
+      Configure MyNuheat account access, HomeKit accessory exposure, and
+      connection behavior.
+    </p>
+  </header>
+
+  <section class="panel">
+    <div class="section-header">
+      <div>
+        <h2>Account</h2>
+        <p class="help">
+          Most homes only need the MyNuheat email and password used by the
+          Nuheat mobile app or web portal.
+        </p>
+      </div>
+      <span id="auth-status" class="status-pill warn">Checking config</span>
+    </div>
+
+    <div class="settings-grid">
+      <label class="field">
+        <span>Platform Name</span>
+        <input id="name" type="text" placeholder="NuHeat" />
+        <small>Name shown in Homebridge logs for this platform instance.</small>
+      </label>
+
+      <label class="field">
+        <span>MyNuheat Email</span>
+        <input id="email" type="email" placeholder="name@example.com" />
+        <small>Email address for the account that owns the thermostats.</small>
+      </label>
+
+      <label id="password-row" class="field">
+        <span>MyNuheat Password</span>
+        <input id="password" type="password" placeholder="Password" />
+        <small>Leave blank to keep an existing saved password.</small>
+      </label>
+    </div>
+
+    <div class="actions">
+      <button id="save-account" class="primary">Save Account</button>
+    </div>
+  </section>
+
+  <section class="panel">
+    <div class="section-header">
+      <div>
+        <h2>Accessories</h2>
+        <p class="help">
+          Leave thermostat and group lists empty to use automatic discovery.
+          Add rows only when you want to limit what appears in HomeKit.
+        </p>
+      </div>
+      <span id="accessory-status" class="status-pill warn">Auto discovery</span>
+    </div>
+
+    <div class="split-grid">
+      <div class="list-panel">
+        <div class="list-heading">
+          <div>
+            <h3>Thermostat Allow-List</h3>
+            <p class="help">
+              Optional serial numbers from MyNuheat.
+            </p>
+          </div>
+          <button id="add-device" class="secondary" type="button">Add</button>
+        </div>
+        <div id="devices-list" class="dynamic-list"></div>
+      </div>
+
+      <div class="list-panel">
+        <div class="list-heading">
+          <div>
+            <h3>Away Mode Groups</h3>
+            <p class="help">
+              Optional group names exactly as shown in MyNuheat.
+            </p>
+          </div>
+          <button id="add-group" class="secondary" type="button">Add</button>
+        </div>
+        <div id="groups-list" class="dynamic-list"></div>
+      </div>
+    </div>
+
+    <label class="checkbox">
+      <input id="auto-populate-away-mode-switches" type="checkbox" />
+      <span>
+        Expose away-mode switches for all groups
+        <small>
+          Automatically creates HomeKit switches for every Nuheat group on the
+          account.
+        </small>
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="expose-schedule-switches" type="checkbox" />
+      <span>
+        Expose schedule switches
+        <small>
+          Adds one switch per thermostat that can resume the Nuheat schedule.
+        </small>
+      </span>
+    </label>
+
+    <div class="actions">
+      <button id="save-accessories" class="primary">Save Accessories</button>
+    </div>
+  </section>
+
+  <section class="panel">
+    <div class="section-header">
+      <div>
+        <h2>Behavior</h2>
+        <p class="help">
+          Tune setpoint holds, polling, Nuheat notifications, and debug logging.
+        </p>
+      </div>
+      <span id="behavior-status" class="status-pill good">Notifications on</span>
+    </div>
+
+    <div class="settings-grid">
+      <label class="field">
+        <span>Hold Length (minutes)</span>
+        <input id="hold-length" type="number" min="0" max="1440" step="1" />
+        <small>
+          0 holds until the next schedule event; 1440 creates a permanent hold.
+        </small>
+      </label>
+
+      <label class="field">
+        <span>Polling Interval (seconds)</span>
+        <input id="refresh" type="number" min="30" step="1" />
+        <small>
+          Polling is a safety net. Values below 30 are raised to 30 at runtime.
+        </small>
+      </label>
+    </div>
+
+    <label class="checkbox">
+      <input id="enable-notifications" type="checkbox" />
+      <span>
+        Enable Nuheat notifications
+        <small>
+          Uses SignalR notifications for faster updates. Disable only while
+          troubleshooting.
+        </small>
+      </span>
+    </label>
+
+    <label class="checkbox">
+      <input id="debug" type="checkbox" />
+      <span>
+        Enable debug logging
+        <small>
+          Writes verbose Nuheat API, notification, and accessory activity to the
+          Homebridge log.
+        </small>
+      </span>
+    </label>
+
+    <div class="actions">
+      <button id="save-behavior" class="primary">Save Behavior</button>
+    </div>
+  </section>
+
+  <section class="panel">
+    <div class="section-header">
+      <div>
+        <h2>Advanced OAuth</h2>
+        <p class="help">
+          Leave these fields blank unless Nuheat has issued confidential-client
+          credentials for testing. PKCE public-client support is planned but is
+          not active yet.
+        </p>
+      </div>
+      <span id="oauth-status" class="status-pill warn">Built-in fallback</span>
+    </div>
+
+    <div class="settings-grid">
+      <label class="field">
+        <span>Nuheat Client ID</span>
+        <input id="client-id" type="text" placeholder="Optional client ID" />
+        <small>Advanced override for a Nuheat-issued OAuth client ID.</small>
+      </label>
+
+      <label id="client-secret-row" class="field">
+        <span>Nuheat Client Secret (Legacy)</span>
+        <input
+          id="client-secret"
+          type="password"
+          placeholder="Leave blank to keep existing"
+        />
+        <small>
+          Required with a custom client ID until PKCE support ships. Do not
+          publish or share this value.
+        </small>
+      </label>
+
+      <label class="field">
+        <span>Nuheat Redirect URI</span>
+        <input id="redirect-uri" type="text" placeholder="http://localhost" />
+        <small>Defaults to http://localhost.</small>
+      </label>
+    </div>
+
+    <div class="actions">
+      <button id="save-oauth" class="primary">Save OAuth Settings</button>
+      <button id="clear-oauth" class="secondary" type="button">
+        Clear Overrides
+      </button>
+    </div>
+  </section>
+
+  <section class="panel">
+    <div class="section-header">
+      <div>
+        <h2>Diagnostics</h2>
+        <p class="help">
+          Review the saved configuration and exposure strategy before
+          restarting Homebridge.
+        </p>
+      </div>
+      <button id="refresh-diagnostics" class="secondary" type="button">
+        Refresh
+      </button>
+    </div>
+    <div id="diagnostics-summary" class="diagnostics-summary muted">
+      No diagnostics loaded yet.
+    </div>
+    <div id="diagnostics-empty" class="help hidden">
+      Save settings to generate a configuration summary.
+    </div>
+    <div id="diagnostics-list" class="diagnostics-list"></div>
+  </section>
+</main>
+
+<div id="toast-container" class="toast-container"></div>
+
+<script src="index.js"></script>