homebridge-tesy-native 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0 — 2026-10-22
+
+- Initial MyTESY cloud convector support based on the supplied Home Assistant integration.
+- Native HomeKit thermostats with Heat/Off and 10–30 °C integer targets.
+- Optional Comfort/Eco/Sleep switches, including return to manual mode.
+- Shared HTTPS discovery/status requests and secure MQTT-over-WebSocket commands.
+- Stable accessory cache IDs and per-device names, exclusions and preset visibility.
+- Idle-safe availability, stale active-heating handling, bounded optimistic updates, command ordering and recovery after cloud failures.
+- Credentials and device tokens excluded from accessory cache metadata and normal/debug output.
+- Homebridge UI schema, source, lockfile, tests and packaging support.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kosztyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,6 @@
+This independently implemented Node.js plugin follows the MyTESY cloud
+protocol used in the user-supplied Home Assistant TESY integration (1.1.0).
+The supplied Python files and vendor JavaScript bundle are not distributed.
+
+TESY and MyTESY are trademarks of their respective owners. This is an
+unofficial community plugin, not a TESY product or endorsement.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# Homebridge TESY Native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MyTESY cloud convectors in Apple Home, implemented from the cloud protocol in the supplied Home Assistant TESY integration 1.1.0. Home Assistant does not need to be running: this plugin communicates with MyTESY directly.
+
+Package: `homebridge-tesy-native` · Platform: `TesyNative` · Author: **Kosztyk** · Version: **1.0.0**
+
+## Features
+
+- Automatically discovers compatible convectors in your MyTESY account.
+- Exposes each convector as a native HomeKit **thermostat**, with **Off / Heat**, current temperature and a **10–30 °C** target in **1 °C** steps.
+- Shows active heating separately from a powered-on heater that is idle.
+- Adds optional **Comfort**, **Eco** and **Sleep** switches, on the same accessory.
+- Supports device naming and exclusions by MAC address, plus per-device preset visibility.
+- Restores accessories with stable IDs after a restart, preserving room assignments.
+- Keeps idle devices available even when their device timestamps stop advancing, following the supplied integration.
+- Reuses a secure MQTT connection for commands and polls device status every 30 seconds by default.
+- Bounds optimistic changes and returns to the reported cloud value if a command is not confirmed.
+- Includes the Homebridge settings schema, ready-to-run JavaScript, tests, lockfile and a GitHub Actions test workflow in the source archive.
+
+## Requirements and device scope
+
+- Node.js **22.12+ within Node 22**, or **Node 24**.
+- Homebridge **1.8+** or **2.x**. Validation uses Homebridge 1.11.1 and 2.4.0 on Node 24.
+- A MyTESY account and compatible internet-connected convector already working with the supplied integration.
+- Outbound HTTPS to `ad.mytesy.com` on port 443 and secure WebSocket access to `mqtt.tesy.com` on port 8083.
+
+This version implements the new MyTESY convector protocol from your integration. It recognises snapshots containing `status`, `temp` and `current_temp`. Legacy TESY Cloud devices and electric water heaters use different commands and are not imported.
+
+The supplied Home Assistant integration also calculates energy estimates and exposes diagnostic sensors. This plugin provides the HomeKit thermostat and presets; it does not reproduce those energy/history sensors or expose unverified writable controls for UV, lock or anti-frost.
+
+## Install the provided package
+
+Copy `homebridge-tesy-native-1.0.0.tgz` onto your Homebridge host, for example into `/tmp`, then run:
+
+```bash
+sudo npm install -g /tmp/homebridge-tesy-native-1.0.0.tgz
+sudo hb-service restart
+```
+
+The package contains the runtime files. There is no TypeScript compilation step. npm installs the MQTT dependency during installation. If your installation uses a different Homebridge restart method, restart it in the Homebridge UI instead.
+
+After restarting, open **Plugins → TESY Native → Settings**, fill in the three account fields, save and restart Homebridge again.
+
+## Account settings
+
+Use the **same email, password value and user ID** configured in your working Home Assistant TESY integration. Its `user_id` field is called `userId` here. It is an account identifier, not a MAC address or an email address. The plugin also accepts `user_id` in manually written JSON for compatibility.
+
+This plugin follows the integration's `/get-my-devices` authentication and does not try to obtain a user ID through a separate login flow. If the Home Assistant configuration uses a portal-provided password value, copy that exact value.
+
+Add this object to the existing `platforms` array, or enter the values in the plugin's settings form:
+
+```json
+{
+  "name": "TESY Native",
+  "username": "your-email@example.com",
+  "password": "YOUR_MYTESY_PASSWORD",
+  "userId": "YOUR_MYTESY_USER_ID",
+  "exposePresets": true,
+  "pollInterval": 30,
+  "platform": "TesyNative"
+}
+```
+
+Leave the device overrides list empty to import all compatible convectors. A blank override row is ignored and cannot disable discovery.
+
+## Device overrides
+
+The discovery log prints the device name, MAC and model. Copy a MAC to override one device:
+
+```json
+"devices": [
+  {
+    "mac": "AA:BB:CC:DD:EE:FF",
+    "name": "Bedroom heater",
+    "exclude": false,
+    "exposePresets": true
+  },
+  {
+    "mac": "11:22:33:44:55:66",
+    "exclude": true
+  }
+]
+```
+
+MAC matching ignores letter case, colons and hyphens. Setting `exclude: true` removes that device's cached accessory; adding it again may require assigning its room again. Devices missing briefly from a cloud response retain their cached identity.
+
+## Thermostat and preset behaviour
+
+| Home action | MyTESY command | Behaviour |
+| --- | --- | --- |
+| Select Heat | `onOff` with `status: on` | Enables the convector; does not claim that the element is already heating. |
+| Select Off | `onOff` with `status: off` | Disables the convector. |
+| Change target | `setTemp` with integer `temp` | Changes the setpoint; does not power the convector on. |
+| Turn a preset on | `setMode` with `name: comfort`, `eco` or `sleep` | Selects that preset and updates all three switches. Preserves the power state. |
+| Turn the selected preset off | `setMode` with `name: heating` | Returns to the manual heating mode defined in the supplied MyTESY portal bundle. Preserves the power state. |
+| Turn an inactive preset off | No command | Leaves the active mode unchanged. |
+
+Preset temperature/time settings continue to use the values configured in MyTESY. A preset switch can remain selected while the thermostat is Off, just as the preset remains configured in the source integration. No cooling or automatic cooling mode is advertised.
+
+Apple Home may group the thermostat and switches into one accessory. Open its accessory settings and choose **Show as Separate Tiles** if you want separate tiles.
+
+## Refresh and availability
+
+| Setting | Default | Meaning |
+| --- | ---: | --- |
+| `pollInterval` | 30 seconds | Time between background cloud polls. Minimum 15 seconds. |
+| `requestTimeout` | 8 seconds | Timeout for an HTTP request, MQTT connection or MQTT publish. |
+| `offlineAfter` | 300 seconds | Time without a successful cloud response containing the device before HomeKit reads report a communication error. |
+| `staleHeatingAfter` | 600 seconds | Maximum age of a device timestamp while it still claims active heating. |
+| `exposePresets` | `true` | Adds the three preset switches. Can be overridden per device. |
+| `debug` | `false` | Logs selected temperature/mode/status fields. |
+
+Status refreshes are shared across accessories and never overlap. HomeKit reads use the most recent snapshot instead of making one request per characteristic.
+
+An old idle/off device timestamp alone does not produce No Response. A stale timestamp that still claims active heating is treated as inactive, matching the supplied integration. Timestamps without a timezone offset are interpreted as UTC, as in its helper.
+
+After a successful MQTT publish, the requested values are shown for up to 15 seconds while polls at approximately 1.5, 5 and 16 seconds look for confirmation. Confirmed values stop being optimistic immediately. If MyTESY keeps reporting the previous value, the plugin restores it and logs a warning. A QoS 0 publish callback confirms that the client sent the message; it is not a device acknowledgement. Failed or timed-out commands are never queued for later replay.
+
+During a short cloud outage the last snapshot remains readable for the configured grace period. A sustained outage reports No Response. Account errors, network errors and recovery are logged without dumping credential-bearing URLs or device tokens.
+
+## Source, testing and packaging
+
+From the extracted source directory:
+
+```bash
+npm ci
+npm run check
+npm test
+npm pack
+```
+
+The resulting `.tgz` includes the entry point, all runtime modules, settings schema and documentation. `package-lock.json`, the test suite and the CI workflow are in the source archive. Runtime dependencies are declared in `package.json`; `homebridge` is a development dependency, not a second Homebridge installation at runtime.
+
+Tests use Homebridge's real accessory and characteristic classes. They cover cloud authentication/errors, MQTT command topics, WebSocket packet transport, safe temperatures, stale/idle status, queued writes, preset semantics, failed commands, confirmation expiry, outage recovery, discovery exclusions, token refresh and accessory restoration. They do not authenticate to a live MyTESY account or operate a physical heater.
+
+## Publishing
+
+The metadata targets `Kosztyk/homebridge-tesy-native`. Create that GitHub repository and upload this source if you want to publish it. The plugin name and `homebridge-plugin` / `supports-hap` keywords are included for Homebridge discovery after npm publication.
+
+After pushing your source and testing it, publish from the source directory with your own npm account:
+
+```bash
+npm login
+npm run check
+npm test
+npm pack --dry-run
+npm publish --access public
+```
+
+The archive is ready for publication; creating it does not publish to GitHub or npm. Registry availability of the package name must be checked when publishing. No Homebridge verification status is claimed.
+
+## References
+
+- User-supplied `tesy.zip`, integration version 1.1.0: `api.py`, `const.py`, `coordinator.py`, `climate.py`, `status.py` and the included portal bundle.
+- [Homebridge dynamic platform API](https://developers.homebridge.io/homebridge/interfaces/DynamicPlatformPlugin.html)
+- [Homebridge plugin conventions](https://github.com/homebridge/plugins)
+- [MQTT.js API](https://github.com/mqttjs/MQTT.js)
+
+MIT license. Unofficial community software.

package/config.example.json

@@ -0,0 +1,9 @@
+{
+  "name": "TESY Native",
+  "username": "your-email@example.com",
+  "password": "YOUR_MYTESY_PASSWORD",
+  "userId": "YOUR_MYTESY_USER_ID",
+  "exposePresets": true,
+  "pollInterval": 30,
+  "platform": "TesyNative"
+}

package/config.schema.json

@@ -0,0 +1,35 @@
+{
+  "pluginAlias": "TesyNative",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Connect MyTESY cloud convectors using the same account details as your Home Assistant TESY integration. Devices appear as thermostats with Heat/Off and a 10–30 °C setpoint.",
+  "schema": {
+    "type": "object",
+    "required": ["username", "password", "userId"],
+    "properties": {
+      "name": {"title": "Plugin name", "type": "string", "default": "TESY Native"},
+      "username": {"title": "MyTESY email", "type": "string", "format": "email", "required": true},
+      "password": {"title": "MyTESY password", "type": "string", "format": "password", "required": true},
+      "userId": {"title": "MyTESY user ID", "type": "string", "required": true, "description": "Use the user_id from your Home Assistant TESY integration. This is the MyTESY account ID, not the device MAC or your email."},
+      "exposePresets": {"title": "Show Comfort / Eco / Sleep switches", "type": "boolean", "default": true, "description": "Selecting a preset preserves the current heater power state. Turning the selected preset off returns to manual heating mode."},
+      "pollInterval": {"title": "Cloud refresh interval (seconds)", "type": "integer", "default": 30, "minimum": 15, "maximum": 3600},
+      "requestTimeout": {"title": "Request timeout (seconds)", "type": "integer", "default": 8, "minimum": 3, "maximum": 15},
+      "offlineAfter": {"title": "Cloud outage grace period (seconds)", "type": "integer", "default": 300, "minimum": 60, "maximum": 3600, "description": "Keep the last snapshot during a short cloud outage. Report No Response after this long without a successful snapshot containing the device."},
+      "staleHeatingAfter": {"title": "Stale active heating threshold (seconds)", "type": "integer", "default": 600, "minimum": 60, "maximum": 7200, "description": "Stop displaying active heating when its device timestamp is too old. Old idle/off timestamps alone do not mark a device offline."},
+      "debug": {"title": "Detailed device status logging", "type": "boolean", "default": false},
+      "devices": {
+        "title": "Optional device overrides", "type": "array",
+        "description": "Leave this empty to discover all compatible convectors. A blank override row is ignored.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "mac": {"title": "Device MAC address", "type": "string", "placeholder": "AA:BB:CC:DD:EE:FF", "description": "Copy the MAC from the Homebridge discovery log."},
+            "name": {"title": "Name override (optional)", "type": "string"},
+            "exclude": {"title": "Exclude this device", "type": "boolean", "default": false},
+            "exposePresets": {"title": "Show preset switches for this device", "type": "boolean", "description": "If omitted, use the plugin-wide setting."}
+          }
+        }
+      }
+    }
+  }
+}

package/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { TesyPlatform } = require('./lib/platform');
+const { PLUGIN_NAME, PLATFORM_NAME } = require('./lib/settings');
+
+module.exports = api => api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, TesyPlatform);

package/lib/accessory.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const { PRESETS } = require('./settings');
+const { finiteNumber, derivedState } = require('./state');
+const { TesyError } = require('./client');
+
+const COMMAND_GRACE_MS = 15000;
+
+class TesyAccessory {
+  constructor(platform, accessory, metadata, options = {}) {
+    this.platform = platform;
+    this.accessory = accessory;
+    this.options = options;
+    this.id = metadata.id;
+    this.name = metadata.name;
+    this.record = null;
+    this.lastSeen = null;
+    this.pending = new Map();
+    this.queue = Promise.resolve();
+    this.configure(metadata);
+  }
+
+  configure(metadata) {
+    const { Service, Characteristic: C } = this.platform.api.hap;
+    const a = this.accessory;
+    a.displayName = this.name;
+    a.getService(Service.AccessoryInformation)
+      .setCharacteristic(C.Manufacturer, 'TESY')
+      .setCharacteristic(C.Model, String(metadata.model || 'Cloud Convector').slice(0, 64))
+      .setCharacteristic(C.SerialNumber, metadata.mac || this.id)
+      .setCharacteristic(C.FirmwareRevision, String(metadata.firmware || 'Unknown').slice(0, 64));
+    this.thermostat = a.getService(Service.Thermostat) || a.addService(Service.Thermostat, this.name);
+    this.thermostat.setPrimaryService(true);
+    this.thermostat.setCharacteristic(C.Name, this.name);
+    if (!this.thermostat.testCharacteristic(C.ConfiguredName)) this.thermostat.addOptionalCharacteristic(C.ConfiguredName);
+    this.thermostat.setCharacteristic(C.ConfiguredName, this.name);
+    this.thermostat.getCharacteristic(C.CurrentTemperature)
+      .setProps({ minValue: -40, maxValue: 100, minStep: 0.1 })
+      .onGet(() => this.readCurrentTemperature());
+    this.thermostat.getCharacteristic(C.TargetTemperature)
+      .setProps({ minValue: 10, maxValue: 30, minStep: 1 })
+      .onGet(() => this.readTargetTemperature())
+      .onSet(value => this.setTemperature(value));
+    this.thermostat.getCharacteristic(C.CurrentHeatingCoolingState).onGet(() => this.readCurrentMode());
+    this.thermostat.getCharacteristic(C.TargetHeatingCoolingState)
+      .setProps({ minValue: C.TargetHeatingCoolingState.OFF, maxValue: C.TargetHeatingCoolingState.HEAT,
+        validValues: [C.TargetHeatingCoolingState.OFF, C.TargetHeatingCoolingState.HEAT] })
+      .onGet(() => this.readTargetMode())
+      .onSet(value => this.setPower(value));
+    this.thermostat.getCharacteristic(C.TemperatureDisplayUnits)
+      .onGet(() => a.context.tesyDisplayUnits ?? C.TemperatureDisplayUnits.CELSIUS)
+      .onSet(value => {
+        if (![C.TemperatureDisplayUnits.CELSIUS, C.TemperatureDisplayUnits.FAHRENHEIT].includes(value)) throw this.invalidValue();
+        a.context.tesyDisplayUnits = value;
+        this.platform.api.updatePlatformAccessories([a]);
+      });
+    if (!this.thermostat.testCharacteristic(C.StatusFault)) this.thermostat.addOptionalCharacteristic(C.StatusFault);
+    this.thermostat.getCharacteristic(C.StatusFault).onGet(() => this.available() ? C.StatusFault.NO_FAULT : C.StatusFault.GENERAL_FAULT);
+
+    const expose = this.options.exposePresets ?? this.platform.config.exposePresets;
+    this.presets = new Map();
+    for (const mode of PRESETS) {
+      const subtype = `tesy:preset:${mode}`;
+      let service = a.getServiceById(Service.Switch, subtype);
+      if (!expose) {
+        if (service) a.removeService(service);
+        continue;
+      }
+      const name = `${this.name} ${mode[0].toUpperCase()}${mode.slice(1)}`;
+      service ||= a.addService(Service.Switch, name, subtype);
+      service.setCharacteristic(C.Name, name);
+      if (!service.testCharacteristic(C.ConfiguredName)) service.addOptionalCharacteristic(C.ConfiguredName);
+      service.setCharacteristic(C.ConfiguredName, name);
+      service.getCharacteristic(C.On)
+        .onGet(() => this.readPreset(mode))
+        .onSet(value => this.setPreset(mode, Boolean(value)));
+      this.presets.set(mode, service);
+    }
+  }
+
+  available() {
+    return this.lastSeen !== null && this.platform.now() - this.lastSeen <= this.platform.config.offlineAfter;
+  }
+
+  communicationError() {
+    const { HapStatusError, HAPStatus } = this.platform.api.hap;
+    return new HapStatusError(HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+  }
+
+  invalidValue() {
+    const { HapStatusError, HAPStatus } = this.platform.api.hap;
+    return new HapStatusError(HAPStatus.INVALID_VALUE_IN_REQUEST);
+  }
+
+  assertAvailable() {
+    if (!this.available() || !this.record) throw this.communicationError();
+  }
+
+  effectiveState() {
+    this.assertAvailable();
+    const state = { ...this.record.state };
+    const now = this.platform.now();
+    for (const [key, pending] of this.pending) {
+      if (now < pending.expires) state[key] = pending.value;
+      else {
+        this.pending.delete(key);
+        if (pending.report) this.platform.log.warn(`[${this.name}] Cloud has not confirmed ${key}; showing its reported value again.`);
+      }
+    }
+    return state;
+  }
+
+  update(record, receivedAt) {
+    this.record = record;
+    this.lastSeen = receivedAt;
+    for (const [key, pending] of this.pending) {
+      if (record.state[key] === pending.value || String(record.state[key]) === String(pending.value)) this.pending.delete(key);
+    }
+    this.updateValues();
+  }
+
+  readCurrentTemperature() {
+    const n = finiteNumber(this.effectiveState().current_temp);
+    if (n === undefined || n < -40 || n > 100) throw this.communicationError();
+    return n;
+  }
+
+  readTargetTemperature() {
+    const n = finiteNumber(this.effectiveState().temp);
+    if (n === undefined || n < 10 || n > 30) throw this.communicationError();
+    return n;
+  }
+
+  readCurrentMode() {
+    const C = this.platform.api.hap.Characteristic;
+    const derived = derivedState(this.effectiveState(), this.platform.now(), this.platform.config.staleHeatingAfter);
+    return derived.heating ? C.CurrentHeatingCoolingState.HEAT : C.CurrentHeatingCoolingState.OFF;
+  }
+
+  readTargetMode() {
+    const C = this.platform.api.hap.Characteristic;
+    const derived = derivedState(this.effectiveState(), this.platform.now(), this.platform.config.staleHeatingAfter);
+    return derived.on ? C.TargetHeatingCoolingState.HEAT : C.TargetHeatingCoolingState.OFF;
+  }
+
+  readPreset(mode) { return this.effectiveState().mode === mode; }
+
+  setTemperature(value) {
+    const n = finiteNumber(value);
+    if (n === undefined || n < 10 || n > 30) return Promise.reject(this.invalidValue());
+    const temp = Math.round(n);
+    return this.mutate(() => ({ command: 'setTemp', payload: { temp }, changes: { temp }, description: `Set temperature to ${temp} °C` }));
+  }
+
+  setPower(value) {
+    const C = this.platform.api.hap.Characteristic;
+    if (![C.TargetHeatingCoolingState.OFF, C.TargetHeatingCoolingState.HEAT].includes(value)) return Promise.reject(this.invalidValue());
+    const on = value === C.TargetHeatingCoolingState.HEAT;
+    return this.mutate(() => {
+      const changes = { status: on ? 'on' : 'off' };
+      const current = derivedState(this.effectiveState(), this.platform.now(), this.platform.config.staleHeatingAfter);
+      // A redundant Heat command preserves fresh, observed heating. A power
+      // command never creates a new claim of active element heating.
+      if (!on || current.staleHeating) changes.heating = 'off';
+      return { command: 'onOff', payload: { status: on ? 'on' : 'off' }, changes, description: on ? 'Turned on' : 'Turned off' };
+    });
+  }
+
+  setPreset(mode, on) {
+    if (!PRESETS.includes(mode)) return Promise.reject(this.invalidValue());
+    return this.mutate(() => {
+      if (!on && this.effectiveState().mode !== mode) return null;
+      const name = on ? mode : 'heating';
+      return { command: 'setMode', payload: { name }, changes: { mode: name }, description: `Selected ${on ? mode : 'manual heating'} mode` };
+    });
+  }
+
+  mutate(build) {
+    const task = this.queue.then(async () => {
+      if (this.platform.stopped) throw this.communicationError();
+      this.assertAvailable();
+      const action = build();
+      if (!action) { this.updateValues(); return; }
+      try {
+        // Resolve metadata here, after preceding writes, so refreshed tokens win.
+        await this.platform.client.sendCommand(this.record.device, action.command, action.payload);
+      } catch (error) {
+        this.platform.log.warn(`[${this.name}] Command failed: ${error instanceof TesyError ? error.message : 'TESY command could not be sent.'}`);
+        throw this.communicationError();
+      }
+      const expires = this.platform.now() + COMMAND_GRACE_MS;
+      for (const [key, val] of Object.entries(action.changes)) {
+        this.pending.set(key, { value: val, expires, report: key !== 'heating' });
+      }
+      this.platform.log.info(`[${this.name}] ${action.description}.`);
+      this.updateValues();
+      this.platform.scheduleCommandRefresh();
+    });
+    this.queue = task.catch(() => {});
+    return task;
+  }
+
+  updateValues() {
+    const C = this.platform.api.hap.Characteristic;
+    const readings = [
+      [C.CurrentTemperature, () => this.readCurrentTemperature()],
+      [C.TargetTemperature, () => this.readTargetTemperature()],
+      [C.CurrentHeatingCoolingState, () => this.readCurrentMode()],
+      [C.TargetHeatingCoolingState, () => this.readTargetMode()],
+    ];
+    for (const [type, read] of readings) {
+      try { this.thermostat.updateCharacteristic(type, read()); }
+      catch { this.thermostat.updateCharacteristic(type, this.communicationError()); }
+    }
+    this.thermostat.updateCharacteristic(C.StatusFault, this.available() ? C.StatusFault.NO_FAULT : C.StatusFault.GENERAL_FAULT);
+    for (const [mode, service] of this.presets) {
+      try { service.updateCharacteristic(C.On, this.readPreset(mode)); }
+      catch { service.updateCharacteristic(C.On, this.communicationError()); }
+    }
+  }
+}
+
+module.exports = { TesyAccessory, COMMAND_GRACE_MS };

package/lib/client.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const { randomBytes } = require('node:crypto');
+const { API_BASE, ORIGIN, MQTT_URL, PRESETS } = require('./settings');
+
+class TesyError extends Error {
+  constructor(message, code = 'CLOUD') {
+    super(message);
+    this.name = 'TesyError';
+    this.code = code;
+  }
+}
+
+class TesyClient {
+  constructor(config, deps = {}) {
+    this.config = config;
+    this.fetch = deps.fetch || globalThis.fetch;
+    this.connect = deps.connect || ((url, options) => require('mqtt').connect(url, options));
+    this.appId = randomBytes(8).toString('hex');
+    this.mqtt = null;
+    this.connecting = null;
+    this.closed = false;
+    this.requests = new Set();
+  }
+
+  async request(path, body) {
+    if (this.closed) throw new TesyError('TESY client is shutting down.', 'CLOSED');
+    const credentials = {
+      userID: this.config.userId, userEmail: this.config.username,
+      userPass: this.config.password, lang: 'en',
+    };
+    const url = new URL(API_BASE + path);
+    const controller = new AbortController();
+    this.requests.add(controller);
+    const timer = setTimeout(() => controller.abort(), this.config.requestTimeout);
+    const options = {
+      method: body ? 'POST' : 'GET', signal: controller.signal, redirect: 'error',
+      headers: { Origin: ORIGIN, Referer: `${ORIGIN}/${body ? 'dashboard' : ''}`, Accept: 'application/json, text/plain, */*' },
+    };
+    if (body) {
+      options.headers['Content-Type'] = 'application/json';
+      options.body = JSON.stringify({ ...body, ...credentials });
+    } else {
+      url.search = new URLSearchParams(credentials).toString();
+    }
+    try {
+      const response = await this.fetch(url, options);
+      if ([401, 403].includes(response.status)) throw new TesyError('MyTESY rejected the account credentials. Check email, password and user ID.', 'AUTH');
+      if (!response.ok) throw new TesyError(`MyTESY returned HTTP ${response.status}.`, 'HTTP');
+      if (body) {
+        // app-log is best effort; drain the response so the connection can be reused.
+        await response.text();
+        return;
+      }
+      let data;
+      try { data = await response.json(); } catch { throw new TesyError('MyTESY returned an invalid JSON response.', 'FORMAT'); }
+      if (!data || typeof data !== 'object' || Array.isArray(data)) throw new TesyError('MyTESY returned an unexpected device list.', 'FORMAT');
+      if (String(data.error) === '1') throw new TesyError('MyTESY rejected the account credentials. Check email, password and user ID.', 'AUTH');
+      if ((data.error !== undefined && !['0', '', 'false', 'null'].includes(String(data.error))) || data.errors) {
+        throw new TesyError('MyTESY reported an error while fetching the device list.', 'CLOUD');
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof TesyError) throw error;
+      // Raw fetch/MQTT errors may contain credentials or tokens in URLs/topics.
+      if (controller.signal.aborted) throw new TesyError('MyTESY request timed out or was cancelled.', 'TIMEOUT');
+      throw new TesyError('Cannot reach MyTESY. Check the internet connection and cloud service.', 'NETWORK');
+    } finally {
+      clearTimeout(timer);
+      this.requests.delete(controller);
+    }
+  }
+
+  getDevices() { return this.request('/get-my-devices'); }
+
+  ensureMqtt() {
+    if (this.closed) return Promise.reject(new TesyError('TESY client is shutting down.', 'CLOSED'));
+    if (this.mqtt?.connected) return Promise.resolve(this.mqtt);
+    if (this.connecting) return this.connecting;
+    if (this.mqtt) this.mqtt.end(true);
+    let client;
+    try {
+      client = this.connect(MQTT_URL, {
+        clientId: `hb_tesy_${this.appId}`, username: 'client1', password: '123',
+        protocolVersion: 4, keepalive: 20, clean: true, reconnectPeriod: 0,
+        connectTimeout: this.config.requestTimeout, queueQoSZero: false, resubscribe: false,
+        rejectUnauthorized: true,
+        wsOptions: { rejectUnauthorized: true, headers: { Origin: ORIGIN } },
+      });
+    } catch { return Promise.reject(new TesyError('Cannot create a secure TESY MQTT connection.', 'MQTT')); }
+    this.mqtt = client;
+    // Always consume async errors, including after an idle connection is lost.
+    client.on('error', () => {});
+    client.on('close', () => { if (this.mqtt === client) this.mqtt = null; });
+    const pending = new Promise((resolve, reject) => {
+      let finished = false;
+      const finish = error => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        client.removeListener('connect', onConnect);
+        client.removeListener('error', onError);
+        client.removeListener('close', onClose);
+        if (error) {
+          if (this.mqtt === client) this.mqtt = null;
+          client.end(true);
+          reject(error);
+        } else resolve(client);
+      };
+      const onConnect = () => finish();
+      const onError = () => finish(new TesyError('TESY MQTT connection failed. Check access to mqtt.tesy.com:8083.', 'MQTT'));
+      const onClose = () => finish(new TesyError('TESY MQTT connection closed before it was ready.', 'MQTT'));
+      const timer = setTimeout(() => finish(new TesyError('TESY MQTT connection timed out.', 'TIMEOUT')), this.config.requestTimeout);
+      client.once('connect', onConnect);
+      client.once('error', onError);
+      client.once('close', onClose);
+    });
+    this.connecting = pending;
+    const clear = () => { if (this.connecting === pending) this.connecting = null; };
+    pending.then(clear, clear);
+    return pending;
+  }
+
+  async sendCommand(device, command, payload) {
+    const mac = String(device.mac || device.state?.mac || '').trim();
+    const model = String(device.model || '').trim();
+    const token = String(device.token || '').trim();
+    if ([mac, model, token].some(v => !v || /[\/+#\u0000]/.test(v))) {
+      throw new TesyError('This device has no valid MAC, model or control token in MyTESY. Refresh device discovery.', 'DEVICE');
+    }
+    const valid = (command === 'onOff' && ['on', 'off'].includes(payload.status))
+      || (command === 'setTemp' && Number.isInteger(payload.temp) && payload.temp >= 10 && payload.temp <= 30)
+      || (command === 'setMode' && [...PRESETS, 'heating'].includes(payload.name));
+    if (!valid) throw new TesyError('Unsupported TESY command or value.', 'COMMAND');
+    const client = await this.ensureMqtt();
+    if (this.closed || !client.connected) throw new TesyError('TESY MQTT is not connected.', 'MQTT');
+    await new Promise((resolve, reject) => {
+      let finished = false;
+      const finish = error => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        client.removeListener('close', onClose);
+        client.removeListener('error', onError);
+        if (error) {
+          if (this.mqtt === client) this.mqtt = null;
+          client.end(true);
+          reject(error);
+        } else resolve();
+      };
+      const onClose = () => finish(new TesyError('TESY MQTT disconnected while sending the command.', 'MQTT'));
+      const onError = () => finish(new TesyError('TESY MQTT could not send the command.', 'MQTT'));
+      const timer = setTimeout(() => finish(new TesyError('TESY command publish timed out.', 'TIMEOUT')), this.config.requestTimeout);
+      client.once('close', onClose);
+      client.once('error', onError);
+      try {
+        client.publish(`v1/${mac}/request/${model}/${token}/${command}`,
+          JSON.stringify({ app_id: this.appId, ...payload }), { qos: 0, retain: false },
+          error => finish(error ? new TesyError('TESY MQTT could not send the command.', 'MQTT') : undefined));
+      } catch { finish(new TesyError('TESY MQTT could not send the command.', 'MQTT')); }
+    });
+    // MQTT publishing is the control path; failure of the app's audit endpoint
+    // must not turn a successful publish into a HomeKit error or a retry.
+    void this.request('/app-log', { mac, command, payload }).catch(() => {});
+  }
+
+  close() {
+    this.closed = true;
+    for (const controller of this.requests) controller.abort();
+    if (this.mqtt) this.mqtt.end(true);
+    this.mqtt = null;
+  }
+}
+
+module.exports = { TesyClient, TesyError };

package/lib/platform.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const { TesyClient, TesyError } = require('./client');
+const { TesyAccessory } = require('./accessory');
+const { PLUGIN_NAME, PLATFORM_NAME, configuration, normaliseMac } = require('./settings');
+const { normaliseDevices } = require('./state');
+
+class TesyPlatform {
+  constructor(log, config, api, deps = {}) {
+    this.log = log;
+    this.api = api;
+    this.config = configuration(config);
+    this.now = deps.now || Date.now;
+    this.client = deps.client || new TesyClient(this.config);
+    this.cached = new Map();
+    this.controllers = new Map();
+    this.commandTimers = new Set();
+    this.refreshing = null;
+    this.stopped = false;
+    this.launched = false;
+    this.lastError = null;
+    this.lastCount = null;
+    api.on('didFinishLaunching', () => { void this.start(); });
+    api.on('shutdown', () => this.stop());
+  }
+
+  override(id) { return this.config.devices.find(d => d.mac === id) || {}; }
+
+  configureAccessory(accessory) {
+    const metadata = accessory.context.tesy;
+    const id = normaliseMac(metadata?.mac || metadata?.id);
+    if (!id) {
+      this.log.warn(`Ignoring a TESY cache entry with no device ID: ${accessory.displayName}`);
+      return;
+    }
+    this.cached.set(id, accessory);
+    if (this.override(id).exclude === true) return;
+    const meta = { ...metadata, id, name: this.override(id).name?.trim() || metadata.name || accessory.displayName };
+    this.controllers.set(id, new TesyAccessory(this, accessory, meta, this.override(id)));
+  }
+
+  async start() {
+    if (this.launched || this.stopped) return;
+    this.launched = true;
+    for (const id of this.cached.keys()) if (this.override(id).exclude === true) this.removeExcluded(id);
+    if (!this.config.username || !this.config.password || !this.config.userId) {
+      this.log.error('Enter the MyTESY email, password and user ID in the TESY Native settings, then restart Homebridge.');
+      return;
+    }
+    const tick = async () => {
+      await this.refresh();
+      if (this.stopped) return;
+      const delay = this.lastError === 'AUTH' ? Math.max(60000, this.config.pollInterval) : this.config.pollInterval;
+      this.pollTimer = setTimeout(() => { void tick(); }, delay);
+      this.pollTimer.unref?.();
+    };
+    await tick();
+  }
+
+  removeExcluded(id) {
+    const accessory = this.cached.get(id);
+    if (accessory) {
+      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+      this.log.info(`Excluded device: ${accessory.displayName}`);
+    }
+    this.controllers.delete(id);
+    this.cached.delete(id);
+  }
+
+  refresh() {
+    if (this.stopped) return Promise.resolve(false);
+    if (this.refreshing) return this.refreshing;
+    const task = this.refreshOnce();
+    this.refreshing = task;
+    const clear = () => { if (this.refreshing === task) this.refreshing = null; };
+    task.then(clear, clear);
+    return task;
+  }
+
+  async refreshOnce() {
+    try {
+      const raw = await this.client.getDevices();
+      if (this.stopped) return false;
+      const records = normaliseDevices(raw);
+      const now = this.now();
+      const seen = new Set();
+      for (const [id, record] of records) {
+        const options = this.override(id);
+        if (options.exclude === true) { this.removeExcluded(id); continue; }
+        seen.add(id);
+        const name = typeof options.name === 'string' && options.name.trim() ? options.name.trim() : record.name;
+        const metadata = {
+          id, mac: record.mac, name,
+          model: String(record.device.model_type || record.device.model || 'Cloud Convector'),
+          firmware: String(record.device.firmware_version || 'Unknown'),
+        };
+        let accessory = this.cached.get(id);
+        const fresh = !accessory;
+        if (fresh) {
+          accessory = new this.api.platformAccessory(name, this.api.hap.uuid.generate(`tesy:${id}`), this.api.hap.Categories.THERMOSTAT);
+          this.cached.set(id, accessory);
+        }
+        let controller = this.controllers.get(id);
+        const changed = JSON.stringify(accessory.context.tesy) !== JSON.stringify(metadata);
+        // Only persist safe identity fields. Cloud tokens and account credentials
+        // stay in memory and never enter Homebridge's accessory cache.
+        accessory.context.tesy = metadata;
+        if (!controller) {
+          controller = new TesyAccessory(this, accessory, metadata, options);
+          this.controllers.set(id, controller);
+        } else if (changed) {
+          controller.name = name;
+          controller.configure(metadata);
+        }
+        controller.update(record, now);
+        if (fresh) {
+          this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+          this.log.info(`Added TESY thermostat: ${name} (${record.mac}, ${metadata.model})`);
+        } else if (changed) this.api.updatePlatformAccessories([accessory]);
+        if (this.config.debug) this.log.info(`[${name}] Temperature ${record.state.current_temp} °C, target ${record.state.temp} °C, status ${record.state.status}, heating ${record.state.heating}, mode ${record.state.mode}.`);
+      }
+      for (const [id, controller] of this.controllers) if (!seen.has(id)) controller.updateValues();
+      if (this.lastError) this.log.info('MyTESY cloud connection recovered.');
+      this.lastError = null;
+      if (this.lastCount !== seen.size) {
+        if (seen.size === 0) this.log.warn('No compatible MyTESY convectors found. Check the account, user ID and device exclusions. Legacy TESY Cloud devices and water heaters use another protocol.');
+        else this.log.info(`Found ${seen.size} TESY convector${seen.size === 1 ? '' : 's'}.`);
+        this.lastCount = seen.size;
+      }
+      return true;
+    } catch (error) {
+      const code = error instanceof TesyError ? error.code : 'INTERNAL';
+      if (this.lastError !== code) {
+        this.log.warn(`TESY refresh failed: ${error instanceof TesyError ? error.message : 'Could not process the MyTESY device list.'} Retrying automatically.`);
+      }
+      this.lastError = code;
+      for (const controller of this.controllers.values()) controller.updateValues();
+      return false;
+    }
+  }
+
+  scheduleCommandRefresh() {
+    if (this.stopped) return;
+    for (const timer of this.commandTimers) clearTimeout(timer);
+    this.commandTimers.clear();
+    for (const delay of [1500, 5000, 16000]) {
+      const timer = setTimeout(() => {
+        this.commandTimers.delete(timer);
+        void this.refresh();
+      }, delay);
+      timer.unref?.();
+      this.commandTimers.add(timer);
+    }
+  }
+
+  stop() {
+    this.stopped = true;
+    clearTimeout(this.pollTimer);
+    for (const timer of this.commandTimers) clearTimeout(timer);
+    this.commandTimers.clear();
+    this.client.close();
+  }
+}
+
+module.exports = { TesyPlatform };

package/lib/settings.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const PLUGIN_NAME = 'homebridge-tesy-native';
+const PLATFORM_NAME = 'TesyNative';
+const API_BASE = 'https://ad.mytesy.com/rest';
+const ORIGIN = 'https://v4.mytesy.com';
+const MQTT_URL = 'wss://mqtt.tesy.com:8083/';
+const PRESETS = ['comfort', 'eco', 'sleep'];
+
+function bounded(value, fallback, min, max) {
+  const n = value === '' || value === null ? NaN : Number(value);
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+}
+
+function normaliseMac(value) {
+  const s = String(value ?? '').trim().replace(/[:-]/g, '').toUpperCase();
+  return /^[0-9A-F]{12}$/.test(s) ? s : '';
+}
+
+function configuration(config = {}) {
+  if (!config || typeof config !== 'object') config = {};
+  const userId = String(config.userId ?? config.user_id ?? '').trim();
+  return {
+    username: String(config.username ?? '').trim(),
+    password: String(config.password ?? ''),
+    userId,
+    pollInterval: bounded(config.pollInterval, 30, 15, 3600) * 1000,
+    requestTimeout: bounded(config.requestTimeout, 8, 3, 15) * 1000,
+    offlineAfter: bounded(config.offlineAfter, 300, 60, 3600) * 1000,
+    staleHeatingAfter: bounded(config.staleHeatingAfter, 600, 60, 7200) * 1000,
+    exposePresets: config.exposePresets !== false,
+    debug: config.debug === true,
+    devices: (Array.isArray(config.devices) ? config.devices : [])
+      .filter(d => d && typeof d === 'object' && normaliseMac(d.mac))
+      .map(d => ({
+        mac: normaliseMac(d.mac),
+        name: typeof d.name === 'string' ? d.name.trim() : undefined,
+        exclude: d.exclude === true,
+        exposePresets: typeof d.exposePresets === 'boolean' ? d.exposePresets : undefined,
+      })),
+  };
+}
+
+module.exports = { PLUGIN_NAME, PLATFORM_NAME, API_BASE, ORIGIN, MQTT_URL, PRESETS, normaliseMac, configuration };

package/lib/state.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { normaliseMac } = require('./settings');
+
+function stateOn(value) {
+  return value === true || value === 1 || (typeof value === 'string' && ['on', '1', 'true'].includes(value.toLowerCase().trim()));
+}
+
+function finiteNumber(value) {
+  if (value === null || value === undefined || typeof value === 'boolean' || String(value).trim() === '') return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function timestamp(value) {
+  if (typeof value !== 'string' || !value.trim()) return undefined;
+  let text = value.trim();
+  // The HA helper treats dates without an explicit offset as UTC.
+  if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(text)) text = text.replace(' ', 'T') + 'Z';
+  const n = Date.parse(text);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function derivedState(state, now, staleAfter) {
+  const updated = timestamp(state.updated_at);
+  const staleHeating = stateOn(state.heating) && (updated === undefined || now - updated > staleAfter);
+  const on = !staleHeating && (stateOn(state.status) || stateOn(state.heating));
+  return { on, heating: !staleHeating && stateOn(state.heating), staleHeating };
+}
+
+function normaliseDevices(raw) {
+  const devices = new Map();
+  for (const [key, value] of Object.entries(raw)) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+    const state = value.state;
+    if (!state || typeof state !== 'object' || Array.isArray(state)) continue;
+    const mac = String(value.mac || state.mac || key).trim();
+    const id = normaliseMac(mac);
+    if (!id) continue;
+    // The supplied integration's commands are for new MyTESY convectors.
+    // Boilers and legacy power_status devices use a different protocol.
+    if (!Object.hasOwn(state, 'status') || !Object.hasOwn(state, 'temp') || !Object.hasOwn(state, 'current_temp')) continue;
+    const kind = String(value.type ?? value.device_type ?? '').toLowerCase();
+    if (kind.includes('boiler') || kind.includes('water')) continue;
+    devices.set(id, {
+      id, mac, device: { ...value, mac }, state: { ...state },
+      name: typeof value.deviceName === 'string' && value.deviceName.trim()
+        ? value.deviceName.trim() : `Tesy Convector ${id.slice(-6)}`,
+    });
+  }
+  return devices;
+}
+
+module.exports = { stateOn, finiteNumber, timestamp, derivedState, normaliseDevices };

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "homebridge-tesy-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "TESY MyTESY cloud convectors for Homebridge: thermostats, temperature control and presets.",
+  "displayName": "TESY Native",
+  "main": "index.js",
+  "type": "commonjs",
+  "engines": {
+    "node": "^22.12.0 || ^24.0.0",
+    "homebridge": "^1.8.0 || ^2.0.0"
+  },
+  "keywords": ["homebridge-plugin", "supports-hap", "homebridge", "homekit", "tesy", "mytesy", "convector", "thermostat", "heater"],
+  "author": {"name": "Kosztyk", "url": "https://github.com/Kosztyk"},
+  "license": "MIT",
+  "repository": {"type": "git", "url": "git+https://github.com/Kosztyk/homebridge-tesy-native.git"},
+  "homepage": "https://github.com/Kosztyk/homebridge-tesy-native#readme",
+  "bugs": {"url": "https://github.com/Kosztyk/homebridge-tesy-native/issues"},
+  "files": ["index.js", "lib/", "scripts/check.js", "config.schema.json", "config.example.json", "README.md", "CHANGELOG.md", "LICENSE", "NOTICE"],
+  "scripts": {
+    "check": "node scripts/check.js",
+    "test": "node --test test/*.test.js",
+    "prepack": "npm run check"
+  },
+  "dependencies": {"mqtt": "^5.16.1"},
+  "devDependencies": {"homebridge": "2.4.0"},
+  "publishConfig": {"access": "public"}
+}

package/scripts/check.js

@@ -0,0 +1,15 @@
+'use strict';
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const root = path.resolve(__dirname, '..');
+const files = ['index.js', ...fs.readdirSync(path.join(root, 'lib')).filter(n => n.endsWith('.js')).map(n => `lib/${n}`)];
+for (const file of files) {
+  const r = spawnSync(process.execPath, ['--check', path.join(root, file)], { stdio: 'inherit' });
+  if (r.status !== 0) process.exit(r.status || 1);
+}
+for (const file of ['package.json', 'config.schema.json', 'config.example.json']) JSON.parse(fs.readFileSync(path.join(root, file), 'utf8'));
+const pkg = require(path.join(root, 'package.json'));
+const schema = require(path.join(root, 'config.schema.json'));
+if (!pkg.keywords.includes('homebridge-plugin') || schema.pluginAlias !== 'TesyNative' || schema.pluginType !== 'platform') throw Error('Invalid Homebridge plugin metadata.');
+console.log('JavaScript syntax, JSON and plugin metadata are valid.');