homebridge-warmup4ie-v2 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to `homebridge-warmup4ie-v2` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+This package is a maintained fork of [`homebridge-warmup4ie`](https://github.com/NorthernMan54/homebridge-warmup4ie). The fork begins at version 2.0.0 (a tribute to the original 1.x lineage) and is published to npm as `homebridge-warmup4ie-v2`. Pre-2.0.0 history below is the upstream history, kept for context.
+
+---
+
+## [2.0.0] — 2026-05-05
+
+**First release of the maintained fork.** Restores the working hard-off that broke in upstream 0.1.0–0.1.1, replaces the deprecated `request` HTTP library with native `fetch`, adds a real test suite, and ships under the new npm name `homebridge-warmup4ie-v2`.
+
+### Migration from `homebridge-warmup4ie`
+
+```bash
+sudo npm uninstall -g homebridge-warmup4ie
+sudo npm install -g homebridge-warmup4ie-v2
+sudo systemctl restart homebridge
+```
+
+Your `config.json` does **not** need changes — the platform identifier (`"platform": "warmup4ie"`) is unchanged for compatibility.
+
+### Why this fork exists
+
+The upstream 0.1.0 PR ("Beta 0.1.0 - HB 2.0 support", Dec 2024) rewrote the API client from function-style to class-style. The rewrite quietly simplified two wire-format details that the Warmup cloud API silently rejects with `200 OK` + `{status:{result:"error"}}`:
+
+- The `setModes locMode: "off"` body lost five required filler keys (`holEnd`, `holStart`, `holTemp`, `fixedTemp`, `geoMode`). HomeKit's "Off" command silently failed for ~5 months while users thought it worked.
+- The `setOverride until` field switched from local time to UTC, breaking override durations by the local timezone offset.
+
+Both regressions were verified byte-for-byte against the [Python reference impl](https://github.com/alex-0103/warmup4IE) and fixed in this release.
+
+### Fixed
+- **`setRoomOff`** — restored the full filler `values` dict. The hard-off that worked in 0.0.14 works again. (Reminder: this is a **location-wide** off — the Warmup mobile app does the same call. The cloud API has no per-room hard-off.)
+- **`setTargetTemperature` `until`** — back to local time.
+- **API errors are surfaced** — `_sendRequest` now fails the callback when the response is `{status:{result:"error"}}`. Both upstream 0.0.14 and 0.1.1 silently treated that as success.
+- **Per-accessory `room` snapshot was frozen at startup.** `updateStatus()` now refreshes `accessory.room` per poll, so `setTargetHeatingCooling`'s `runMode`-based logic sees fresh state.
+
+### Changed
+- **Transport: `request` → native `fetch`.** Drops a 12-year-old deprecated dependency (`request` is unmaintained since 2020 and ships unfixed prototype-pollution / SSRF advisories). Native `fetch` is built into Node ≥18, so no new dep, no install-size cost. Behaviour preserved: same headers, same JSON body, same 10 s timeout (now via `AbortSignal.timeout`).
+- **Polling consolidated.** Upstream had two timers running (`refresh` from the platform, `refresh/2` from the lib) — the API was being hit ~3× per refresh window. The lib timer was removed; the platform now fetches *and* pushes in a single tick at `refresh` seconds.
+- **`SerialNumber` is now `warmup4ie-<roomId>`** instead of `<hostname>-<name>` — stable across host moves, matches HAP-NodeJS guidance on accessory identity.
+- **`setPrimaryService(true)`** is used in place of direct `isPrimaryService = true` (per HAP-NodeJS v2 docs), with a property-assignment fallback for HB 1.x environments.
+- **`updateStatus` refactored** — pure `deriveCurrentHeatingState` / `deriveTargetHeatingState` helpers extracted to `src/lib/state.js`, shared by the initial `getServices()` build and the polling path.
+- **Multi-location accounts: first location only**, by design. Documented explicitly. The Python reference filters by name; we don't, because this plugin has no `location` config knob and adding one is out of scope here. If you need multiple locations on one account, run a second Homebridge child bridge.
+
+### Removed
+- **`request` dependency.** Replaced with native `fetch`.
+- **Unused upstream dependencies:** `fakegato-history`, `homebridge-lib`, `moment`, `semver`. None had a live code path; `fakegato-history` was already commented out in upstream 0.1.1.
+- **Dead code in `index.js`:** commented-out fakegato / CustomCharacteristics blocks; unused `storage` config option (was never wired up); unused `username` / `password` fields on the per-accessory object.
+- **Dead public methods on `Warmup4IE`:** `setRoomOverride`, `setRoomFixed`, `_setRoomMode`, `pollDevices`, `destroy`. None had callers.
+- **Unused constructor options** on `Warmup4IE` (`location`, `room`, `target_temp`, `setup_finished`).
+
+### Added
+- **`LICENSE` file** — Apache-2.0 boilerplate (the original repo declared the license but didn't include the file).
+- **Full test suite** under `test/`:
+  - **Unit** (`test/unit/`): wire-format builders, state derivers (truth tables), `until` time formatting (TZ + DST + wraparound), `_fetch` error paths.
+  - **Integration** (`test/integration/`): full bootstrap chain, polling state propagation, error recovery, plugin loadtime / `registerPlatform` smoke.
+  - **Live** (`test/live/api.test.js`): opt-in via `WARMUP_LIVE_TEST=1`, real `api.warmup.com` calls; plus a destructive `setRoomOff/setRoomAuto` cycle gated behind `WARMUP_LIVE_DESTRUCTIVE=1`.
+  - **Fixtures** (`test/fixtures/`): sanitized JSON snapshots of API responses.
+- **`QA_TESTS.md`** — manual pre-release checklist (~15 min) covering Home app smoke, single-room and multi-room control flows, regression sentinels, edge cases, and rollback.
+- **CI** (`.github/workflows/ci.yml`) — lint + test + smoke on Node 18.20, 20.15, 22 for every push and PR.
+- **Release** (`.github/workflows/release.yml`) — tag-driven (`v*`) publish to npm with provenance, plus a GitHub Release. Verifies the tag matches `package.json` version before publishing.
+
+### Repository
+- **npm name:** `homebridge-warmup4ie-v2` (new; original `homebridge-warmup4ie` is unaffected and still abandoned upstream).
+- **GitHub:** `nookied/homebridge-warmup4ie` (this fork; `upstream` git remote intentionally not configured).
+- **Author:** Karol Nowacki (this fork) + NorthernMan54 (original). Apache-2.0 preserved.
+
+---
+
+## Upstream history (pre-fork)
+
+The entries below are the upstream `NorthernMan54/homebridge-warmup4ie` history, kept here for context. They do not correspond to versions of *this* package — only to versions of the upstream package on npm.
+
+### upstream 0.1.1 — 2024-12-14
+
+Final upstream `package.json` bump on top of 0.1.0 beta after merging HB 2.0 support to `main`. No source changes since the merge commit. **`Off` control silently broken** (see "Why this fork exists" above).
+
+### upstream 0.1.0 — 2024-12-13 (the breaking rewrite)
+
+Wholesale rewrite of `lib/warmup4ie.js` from function-style to class-style ("Beta 0.1.0 - HB 2.0 support", PR #7). Added Homebridge 2.0 support, ESLint v9, Jest test sketch, and a CI workflow. Quietly introduced the two wire-format regressions documented above; the resulting plugin loads under HB 2.0 but cannot turn thermostats off and cannot accurately time overrides.
+
+### upstream 0.0.14 — 2021-11-23
+
+Last known-good upstream version. `Off` worked correctly here (full `setModes` body with all filler keys); overrides used local time. Crashed on Homebridge 2.0 + HAP v2 because of a transitive `fakegato-history` incompatibility (`Formats.DATA` undefined), but on HB 1.x it ran cleanly.
+
+### upstream pre-0.0.14 — 2019–2021
+
+Initial development sprint (June 2019, "Day 1"–"Day 7 - Beta ready"), iOS 13 fixes (Sept 2019), small patches (2019–2021). See upstream `git log` for details — commit messages are sparse ("Ooops", "Fix").

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2019-2024 NorthernMan54 (original homebridge-warmup4ie)
+   Copyright 2026 Karol Nowacki (homebridge-warmup4ie-v2 maintained fork)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+# homebridge-warmup4ie-v2
+
+[![npm](https://img.shields.io/npm/v/homebridge-warmup4ie-v2.svg)](https://www.npmjs.com/package/homebridge-warmup4ie-v2)
+[![Apache 2.0](https://img.shields.io/npm/l/homebridge-warmup4ie-v2.svg)](LICENSE)
+
+Homebridge plugin for **[Warmup 4iE](https://www.warmup.com/thermostats/smart/4ie)** underfloor-heating thermostats.
+
+This is a **maintained fork** of [`homebridge-warmup4ie`](https://github.com/NorthernMan54/homebridge-warmup4ie) (NorthernMan54), which became broken at version 0.1.0–0.1.1 in late 2024 and has not been updated since. The original silently rejected the `Off` HomeKit command (location turn-off API was sending the wrong body) and overrode temperatures in UTC instead of local time. This fork restores the working behaviour, replaces the deprecated `request` HTTP library with native `fetch`, and adds a real test suite.
+
+If you have `homebridge-warmup4ie` installed, **uninstall it first** before installing this package — see [Migration](#migration) below.
+
+## Why this fork exists
+
+The 0.1.0 rewrite of the original plugin (PR #7, "Beta 0.1.0 - HB 2.0 support") simplified two wire-format details that the Warmup cloud API silently rejects:
+
+- The `setModes locMode: "off"` body lost five required filler keys (`holEnd`, `holStart`, `holTemp`, `fixedTemp`, `geoMode`). The API responds with `200 OK` + `{status:{result:"error"}}` — the plugin treated that as success, so HomeKit reported "Off" while the thermostats kept heating.
+- The override `until` time switched from local-time `HH:MM` to UTC, making boost overrides expire at the wrong wall-clock time.
+
+Both regressions were verified byte-for-byte against the [Python reference implementation](https://github.com/alex-0103/warmup4IE) and fixed in this fork's first release. See [CHANGELOG.md](CHANGELOG.md) for the full restoration story.
+
+## Install
+
+```bash
+sudo npm install -g homebridge-warmup4ie-v2
+```
+
+Or via the Homebridge UI: search for **homebridge-warmup4ie-v2** in the plugin browser.
+
+To install straight from git instead of npm (e.g. to pin a specific commit):
+
+```bash
+sudo npm install -g github:nookied/homebridge-warmup4ie
+```
+
+## Configuration
+
+Add a platform entry to your Homebridge `config.json`:
+
+```jsonc
+{
+  "platforms": [
+    {
+      "platform": "warmup4ie",
+      "name": "WarmUP",
+      "username": "you@example.com",
+      "password": "your-my.warmup.com-password",
+      "refresh": 60,
+      "duration": 60
+    }
+  ]
+}
+```
+
+| Key | Required | Default | Notes |
+|---|---|---|---|
+| `platform` | yes | — | Must be exactly `"warmup4ie"` (the platform identifier — same as the original plugin, so existing configs migrate without edits) |
+| `name` | yes | — | Display name in Homebridge logs |
+| `username` | yes | — | Your my.warmup.com email |
+| `password` | yes | — | Your my.warmup.com password |
+| `refresh` | no | `60` | API polling interval, seconds |
+| `duration` | no | `60` | Override duration, minutes — how long a manual temperature change stays active before the schedule resumes |
+
+## Behaviour
+
+### Temperature changes
+Any temperature change in HomeKit creates a Warmup **override** lasting `duration` minutes. After that, the room returns to whatever schedule was active before.
+
+### Modes
+HomeKit thermostats expose four modes; this plugin only uses three:
+
+| HomeKit | Action on Warmup |
+|---|---|
+| **Off** | Sends `setModes locMode=off` — turns off the **whole location** (see below). Same behaviour as the Warmup mobile app's "Off" button. |
+| **Heat** | Resumes the room's program. If the room is already in `fixed` or `override` state, no-op (preserves the override). |
+| **Auto** | Resumes the room's program (same as Heat). |
+| **Cool** | Not used — Warmup is a heating-only system. |
+
+### Off is location-wide, not per-room
+The Warmup cloud API has no per-room hard-off operation — confirmed against the Python reference impl and the mobile app's wire traffic. If you have multiple rooms on one account, tapping "Off" on **any** room turns the whole location off. This is the API contract, not a plugin limitation. If you want a per-room "off" effect, set `Heat` mode and drop the temperature to a frost setpoint (~5°C); the room stops heating until you raise it again.
+
+## Migration
+
+If you're moving from the original `homebridge-warmup4ie`:
+
+```bash
+sudo npm uninstall -g homebridge-warmup4ie
+sudo npm install -g homebridge-warmup4ie-v2
+sudo systemctl restart homebridge   # or: hb-service restart
+```
+
+**Your `config.json` does not need changes.** The platform identifier (`"platform": "warmup4ie"`) is unchanged for compatibility — only the npm package name differs.
+
+If accessories appear duplicated after migration, clear Homebridge's cached accessories from the UI (Settings → Remove Single Cached Accessory) for the orphaned ones from the old plugin.
+
+## Troubleshooting
+
+### Plugin won't start, error mentions `fakegato-history`
+You're still on `homebridge-warmup4ie@0.0.14` or older. Uninstall it (`sudo npm uninstall -g homebridge-warmup4ie`) and install this fork.
+
+### "Off" doesn't actually stop the heat
+On `homebridge-warmup4ie@0.1.0` or `0.1.1`? That version has the broken `setRoomOff` body. Switch to this fork.
+
+### "Not Responding" in Home app after a control action
+The Warmup API rejected the call (e.g. invalid credentials, expired token, server error). Check the Homebridge log for `Warmup API: ...` errors. This plugin surfaces API-level errors instead of swallowing them; that's intentional — the original plugin would silently report success.
+
+### Multi-location accounts
+This plugin uses the **first** location only (`locations[0].id`). If you have e.g. a primary residence + a holiday home on the same Warmup account, only the first one is exposed. Run a second Homebridge instance/child bridge with a different account to expose the other location.
+
+### Live API debugging
+```bash
+DEBUG=warmup4ie* sudo -E systemctl restart homebridge
+sudo journalctl -u homebridge -f
+```
+
+## Development
+
+```bash
+git clone https://github.com/nookied/homebridge-warmup4ie.git
+cd homebridge-warmup4ie
+npm install
+npm run lint                  # ESLint
+npm test                      # Jest — unit + integration (no network)
+npm run watch                 # Run plugin against test/hbConfig sandbox
+
+WARMUP_LIVE_TEST=1 \
+WARMUP_USERNAME=you@example.com \
+WARMUP_PASSWORD=... \
+  npm test                    # Adds the live-API test suite
+```
+
+See [QA_TESTS.md](QA_TESTS.md) for the manual pre-release checklist.
+
+## Versioning
+
+This fork starts at **2.0.0** as a tribute to the original v1 lineage. From here, the fork follows [Semantic Versioning](https://semver.org/):
+
+| Bump | When |
+|---|---|
+| **MAJOR** (`X.0.0`) | Breaking change to config keys or HomeKit accessory shape |
+| **MINOR** (`X.Y.0`) | New feature (e.g. multi-location config, new HomeKit service) |
+| **PATCH** (`X.Y.Z`) | Bug fix, dependency bump, doc-only change |
+
+Releases are tag-driven: `npm version patch && git push --follow-tags` triggers the publish workflow.
+
+## License
+
+[Apache 2.0](LICENSE). Copyright 2019–2024 NorthernMan54 (original) + 2026 Karol Nowacki (this fork). The Apache-2.0 license is preserved from the original.
+
+## Credits
+
+- **NorthernMan54** — original `homebridge-warmup4ie` (2019), the basis for this fork.
+- **alex-0103** — [`warmup4IE`](https://github.com/alex-0103/warmup4IE) Python reference implementation, the source of truth for the Warmup cloud API wire format.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "homebridge-warmup4ie-v2",
+  "version": "2.0.0",
+  "description": "Homebridge plugin for Warmup 4iE underfloor-heating thermostats. Maintained fork of homebridge-warmup4ie with fixes for Homebridge 2.0 and the broken Off control in 0.1.0–0.1.1.",
+  "main": "src/index.js",
+  "scripts": {
+    "lint": "eslint --max-warnings=0 .",
+    "lint:fix": "eslint --fix --max-warnings=0 .",
+    "watch": "nodemon",
+    "test": "jest --detectOpenHandles",
+    "test-coverage": "jest --coverage",
+    "smoke": "node -e \"const m = require('./src/index.js'); if (typeof m !== 'function') { process.exit(1); }\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nookied/homebridge-warmup4ie.git"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge-warmup4ie",
+    "warmup4ie",
+    "warmup",
+    "thermostat",
+    "underfloor-heating",
+    "homekit"
+  ],
+  "engines": {
+    "homebridge": "^1.6.0 || ^2.0.0-beta.0",
+    "node": "^18.20.4 || ^20.15.1 || ^22.0.0"
+  },
+  "dependencies": {
+    "debug": "^4.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.14.0",
+    "eslint": "^8.57.1",
+    "eslint-plugin-format": "^0.1.2",
+    "eslint-plugin-jest": "^28.8.3",
+    "globals": "^15.12.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.7"
+  },
+  "author": "Karol Nowacki (fork of NorthernMan54/homebridge-warmup4ie)",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/nookied/homebridge-warmup4ie/issues"
+  },
+  "homepage": "https://github.com/nookied/homebridge-warmup4ie#readme",
+  "nodemonConfig": {
+    "watch": [
+      "src"
+    ],
+    "ext": "js",
+    "ignore": [],
+    "exec": "DEBUG=HAP-NodeJS*,warmup4ie* ~/npm/bin/homebridge -U ./test/hbConfig -I -Q -T -D -P .",
+    "signal": "SIGTERM",
+    "env": {
+      "NODE_OPTIONS": "--trace-warnings"
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,208 @@
+// Homebridge platform for Warmup 4iE underfloor-heating thermostats.
+// Each Warmup "room" is exposed as a HomeKit Thermostat (primary) plus a
+// paired TemperatureSensor for the air-temp probe. Static accessory platform
+// (legacy `accessories(callback)` flow) — Homebridge v2 still supports this.
+
+'use strict';
+
+const debug = require('debug')('warmup4ie');
+const { Warmup4IE } = require('./lib/warmup4ie');
+const { deriveCurrentHeatingState, deriveTargetHeatingState } = require('./lib/state');
+const { version: PLUGIN_VERSION, name: PLUGIN_NAME } = require('../package.json');
+
+let Service, Characteristic;
+const myAccessories = [];
+let thermostats;
+
+module.exports = function (homebridge) {
+  Service = homebridge.hap.Service;
+  Characteristic = homebridge.hap.Characteristic;
+
+  // First arg matches the npm package name (Homebridge uses it for plugin
+  // disambiguation). Second arg is the platform identifier users put in
+  // their config.json — kept as `warmup4ie` for migration compatibility.
+  homebridge.registerPlatform(PLUGIN_NAME, 'warmup4ie', warmup4iePlatform);
+};
+
+function warmup4iePlatform(log, config /* , api */) {
+  this.username = config.username;
+  this.password = config.password;
+  this.refresh = config.refresh || 60;   // polling interval, seconds
+  this.duration = config.duration || 60; // override duration, minutes
+  this.log = log;
+}
+
+warmup4iePlatform.prototype = {
+  accessories: function (callback) {
+    this.log('Logging into warmup4ie...');
+
+    thermostats = new Warmup4IE(this, (err, rooms) => {
+      if (err) {
+        this.log.error('Warmup login/initial fetch failed:', err.message);
+        callback([]);
+        return;
+      }
+      this.log('Found %s room(s)', rooms.length);
+      rooms.forEach((room) => {
+        this.log('Adding', room.roomName);
+        myAccessories.push(new Warmup4ieAccessory(this, room.roomName, thermostats.room[room.roomId]));
+      });
+      callback(myAccessories);
+    });
+
+    setInterval(() => {
+      thermostats.getStatus((err) => {
+        if (err) {
+          this.log.error('Warmup poll failed:', err.message);
+          return;
+        }
+        thermostats.room.forEach((room) => {
+          if (room) updateStatus(room);
+        });
+      });
+    }, this.refresh * 1000);
+  }
+};
+
+function getAccessory(accessories, roomId) {
+  return accessories.find((accessory) => accessory.roomId === roomId);
+}
+
+function updateStatus(room) {
+  const acc = getAccessory(myAccessories, room.roomId);
+  if (!acc) return;
+
+  // Refresh the per-accessory snapshot so .runMode-dependent setters see fresh state.
+  acc.room = room;
+
+  const targetTemperature = (room.targetTemp > room.minTemp ? room.targetTemp : room.minTemp);
+  acc.thermostatService
+    .getCharacteristic(Characteristic.TargetTemperature)
+    .updateValue(Number(targetTemperature / 10));
+
+  acc.thermostatService
+    .getCharacteristic(Characteristic.CurrentTemperature)
+    .updateValue(Number(room.currentTemp / 10));
+
+  acc.thermostatService
+    .getCharacteristic(Characteristic.CurrentHeatingCoolingState)
+    .updateValue(deriveCurrentHeatingState(room));
+
+  acc.thermostatService
+    .getCharacteristic(Characteristic.TargetHeatingCoolingState)
+    .updateValue(deriveTargetHeatingState(room));
+
+  acc.temperatureService
+    .getCharacteristic(Characteristic.CurrentTemperature)
+    .updateValue(Number(room.airTemp / 10));
+}
+
+function Warmup4ieAccessory(that, name, room) {
+  this.log = that.log;
+  this.log('Adding warmup4ie Device', name);
+  this.name = name;
+  this.room = room;
+  this.roomId = room.roomId;
+}
+
+Warmup4ieAccessory.prototype = {
+
+  setTargetHeatingCooling: function (value, callback) {
+    this.log('Setting system switch for', this.name, 'to', value);
+    switch (value) {
+      case 0: // Off (location-wide — see lib note)
+        thermostats.setRoomOff(this.roomId, (err, json) => {
+          if (err) return callback(err);
+          debug('setRoomOff - Result', json);
+          callback(null);
+        });
+        break;
+      case 1: // Heat — keep override/fixed if already set, otherwise resume schedule
+        if (this.room.runMode === 'fixed' || this.room.runMode === 'override') {
+          callback(null);
+        } else {
+          thermostats.setRoomAuto(this.roomId, (err, json) => {
+            if (err) return callback(err);
+            debug('setRoomAuto - Result', json);
+            callback(null);
+          });
+        }
+        break;
+      case 3: // Auto
+        thermostats.setRoomAuto(this.roomId, (err, json) => {
+          if (err) return callback(err);
+          debug('setRoomAuto - Result', json);
+          callback(null);
+        });
+        break;
+      default:
+        callback(null);
+    }
+  },
+
+  setTargetTemperature: function (value, callback) {
+    this.log('Setting target temperature for', this.name, 'to', value + '°');
+    thermostats.setTargetTemperature(this.roomId, value, (err, json) => {
+      if (err) return callback(err);
+      debug('setTargetTemperature - Result', json);
+      callback(null);
+    });
+  },
+
+  getServices: function () {
+    const informationService = new Service.AccessoryInformation()
+      .setCharacteristic(Characteristic.Manufacturer, 'warmup4ie')
+      // Stable serial: roomId is unique per Warmup account and survives host moves.
+      .setCharacteristic(Characteristic.SerialNumber, `warmup4ie-${this.roomId}`)
+      .setCharacteristic(Characteristic.FirmwareRevision, PLUGIN_VERSION);
+
+    this.temperatureService = new Service.TemperatureSensor(this.name + ' Air');
+    this.temperatureService
+      .getCharacteristic(Characteristic.CurrentTemperature)
+      .setProps({ minValue: -100, maxValue: 100 })
+      .updateValue(Number(this.room.airTemp / 10));
+
+    this.thermostatService = new Service.Thermostat(this.name);
+    if (typeof this.thermostatService.setPrimaryService === 'function') {
+      this.thermostatService.setPrimaryService(true);
+    } else {
+      this.thermostatService.isPrimaryService = true;
+    }
+
+    this.thermostatService
+      .getCharacteristic(Characteristic.TargetHeatingCoolingState)
+      .setProps({ validValues: [0, 1, 3] })
+      .on('set', this.setTargetHeatingCooling.bind(this));
+
+    this.thermostatService
+      .getCharacteristic(Characteristic.TargetTemperature)
+      .setProps({
+        minValue: this.room.minTemp / 10,
+        maxValue: this.room.maxTemp / 10
+      })
+      .on('set', this.setTargetTemperature.bind(this));
+
+    this.thermostatService
+      .getCharacteristic(Characteristic.CurrentTemperature)
+      .setProps({ minValue: -100, maxValue: 100 });
+
+    const targetTemperature = (this.room.targetTemp > this.room.minTemp ? this.room.targetTemp : this.room.minTemp);
+    this.thermostatService
+      .getCharacteristic(Characteristic.TargetTemperature)
+      .updateValue(Number(targetTemperature / 10));
+
+    this.thermostatService
+      .getCharacteristic(Characteristic.CurrentTemperature)
+      .updateValue(Number(this.room.currentTemp / 10));
+
+    this.thermostatService
+      .getCharacteristic(Characteristic.CurrentHeatingCoolingState)
+      .updateValue(deriveCurrentHeatingState(this.room));
+
+    this.thermostatService
+      .getCharacteristic(Characteristic.TargetHeatingCoolingState)
+      .updateValue(deriveTargetHeatingState(this.room));
+
+    return [informationService, this.thermostatService, this.temperatureService];
+  }
+};

package/src/lib/state.js

@@ -0,0 +1,24 @@
+'use strict';
+
+// Pure mappings from Warmup `room` payloads to HAP HeatingCoolingState values.
+// Extracted so unit tests can exercise the truth table without spinning up
+// HAP-NodeJS. Numeric values are HAP characteristic values:
+//   CurrentHeatingCoolingState: 0=OFF, 1=HEAT, 2=COOL  (we only emit 0 and 1)
+//   TargetHeatingCoolingState:  0=OFF, 1=HEAT, 2=COOL, 3=AUTO  (we only emit 0, 1, 3)
+
+function deriveCurrentHeatingState(room) {
+  if (room.runMode === 'off') return 0;
+  return room.currentTemp < room.targetTemp ? 1 : 0;
+}
+
+function deriveTargetHeatingState(room) {
+  switch (room.runMode) {
+    case 'off': return 0;
+    case 'fixed':
+    case 'override': return 1;
+    case 'schedule': return 3;
+    default: return 1;
+  }
+}
+
+module.exports = { deriveCurrentHeatingState, deriveTargetHeatingState };

package/src/lib/warmup4ie.js

@@ -0,0 +1,200 @@
+'use strict';
+
+const debug = require('debug')('warmup4ie:lib');
+
+const TOKEN_URL = 'https://api.warmup.com/apps/app/v1';
+const APP_TOKEN = 'M=;He<Xtg"$}4N%5k{$:PD+WA"]D<;#PriteY|VTuA>_iyhs+vA"4lic{6-LqNM:';
+const REQUEST_HEADERS = {
+  'user-agent': 'WARMUP_APP',
+  'accept-encoding': 'br, gzip, deflate',
+  'accept': '*/*',
+  'content-type': 'application/json',
+  'app-token': APP_TOKEN,
+  'app-version': '1.8.1',
+  'accept-language': 'de-de'
+};
+const REQUEST_TIMEOUT_MS = 10000;
+
+let WarmupAccessToken = null;
+let LocId = null;
+
+class Warmup4IE {
+  constructor(options, callback) {
+    this._username = options.username;
+    this._password = options.password;
+    this._duration = options.duration;
+    this.room = [];
+
+    this._bootstrap().then(
+      (rooms) => callback(null, rooms),
+      (err) => callback(err)
+    );
+  }
+
+  async _bootstrap() {
+    await this._generateAccessToken();
+    await this._getLocations();
+    return this._fetchRooms();
+  }
+
+  // Public callback-style transport. Stubbed by tests.
+  _sendRequest(body, callback) {
+    this._fetch(body).then(
+      (json) => callback(null, json),
+      (err) => {
+        console.error(err);
+        callback(err);
+      }
+    );
+  }
+
+  async _fetch(body) {
+    let response;
+    try {
+      response = await fetch(TOKEN_URL, {
+        method: 'POST',
+        headers: REQUEST_HEADERS,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
+    } catch (ex) {
+      throw new Error(`Warmup network error: ${ex.message}`);
+    }
+
+    if (!response.ok) {
+      throw new Error(`Warmup HTTP ${response.status}`);
+    }
+
+    const text = await response.text();
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch (ex) {
+      throw new Error(`Warmup JSON parse error: ${ex.message}`);
+    }
+
+    // The Warmup API returns 200 with `{status:{result:"error",...}}` on rejection.
+    if (json.status && json.status.result !== 'success') {
+      const msg = json.message || json.status.message || JSON.stringify(json.status);
+      throw new Error(`Warmup API: ${msg}`);
+    }
+
+    return json;
+  }
+
+  async _generateAccessToken() {
+    const json = await this._fetch({
+      request: {
+        email: this._username,
+        password: this._password,
+        method: 'userLogin',
+        appId: 'WARMUP-APP-V001'
+      }
+    });
+    WarmupAccessToken = json.response.token;
+  }
+
+  // By design: multi-location accounts use the first location only. The Warmup
+  // app does the same when no location is explicitly selected. If you need a
+  // second location, run a second Homebridge child bridge with another account.
+  async _getLocations() {
+    if (!WarmupAccessToken) throw new Error('Missing access token.');
+
+    const json = await this._fetch({
+      account: { email: this._username, token: WarmupAccessToken },
+      request: { method: 'getLocations' }
+    });
+
+    const first = json.response.locations && json.response.locations[0];
+    if (!first) throw new Error('No locations on Warmup account.');
+    LocId = first.id;
+  }
+
+  async _fetchRooms() {
+    if (!LocId || !WarmupAccessToken) throw new Error('Missing LocId or access token.');
+
+    const json = await this._fetch({
+      account: { email: this._username, token: WarmupAccessToken },
+      request: { method: 'getRooms', locId: LocId }
+    });
+
+    const rooms = json.response.rooms || [];
+    rooms.forEach((room) => {
+      this.room[room.roomId] = room;
+    });
+    return rooms;
+  }
+
+  getStatus(callback) {
+    this._fetchRooms().then(
+      (rooms) => callback(null, rooms),
+      (err) => callback(err)
+    );
+  }
+
+  setTargetTemperature(roomId, value, callback) {
+    // `until` is local-time HH:MM. The Warmup app sends local time; UTC here makes
+    // the override expire at the wrong wall-clock time (off by the timezone offset).
+    const end = new Date(Date.now() + this._duration * 60000);
+    const until = `${String(end.getHours()).padStart(2, '0')}:${String(end.getMinutes()).padStart(2, '0')}`;
+
+    const body = {
+      account: { email: this._username, token: WarmupAccessToken },
+      request: {
+        method: 'setOverride',
+        rooms: [roomId],
+        type: 3,
+        temp: parseInt(value * 10, 10),
+        until
+      }
+    };
+
+    debug('setTargetTemperature', JSON.stringify(body));
+    this.room[roomId] = null;
+    this._sendRequest(body, callback);
+  }
+
+  setRoomAuto(roomId, callback) {
+    const body = {
+      account: { email: this._username, token: WarmupAccessToken },
+      request: {
+        method: 'setProgramme',
+        roomId,
+        roomMode: 'prog'
+      }
+    };
+
+    this.room[roomId] = null;
+    this._sendRequest(body, callback);
+  }
+
+  // Hard-off — the Warmup mobile app does this exact same call when you turn a
+  // thermostat off, which is location-wide (`locMode: off`). There is no
+  // per-room hard-off in the Warmup API; this is the documented behaviour.
+  // Filler keys (`holEnd`, `holStart`, `holTemp`, `fixedTemp`, `geoMode`) are
+  // *required* — without them the API returns 200 OK with a JSON error body
+  // and the thermostats never receive the command. Match the Python reference
+  // body byte-for-byte (alex-0103/warmup4IE).
+  setRoomOff(roomId, callback) {
+    const body = {
+      account: { email: this._username, token: WarmupAccessToken },
+      request: {
+        method: 'setModes',
+        values: {
+          holEnd: '-',
+          fixedTemp: '',
+          holStart: '-',
+          geoMode: '0',
+          holTemp: '-',
+          locId: LocId,
+          locMode: 'off'
+        }
+      }
+    };
+
+    this.room[roomId] = null;
+    this._sendRequest(body, callback);
+  }
+}
+
+module.exports = { Warmup4IE };