homebridge-slwf-01pro 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to `homebridge-SLWF-01Pro` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+This package is a maintained fork of [`homebridge-esphome-ac`](https://github.com/nitaybz/homebridge-esphome-ac). Pre-fork history below is the upstream history, kept for context.
+
+---
+
+## [0.1.0] — Unreleased
+
+First fork release — bug fixes, full multi-entity rewrite, and a substantial feature expansion. Adds mDNS auto-discovery, multi-entity HomeKit composition (humidity / outdoor temperature / power / beeper / display switches), DRY + FAN_ONLY mode tiles, Eve.Energy power graphs, and HEAT_COOL-mode AC support. Three independent code-review passes drove a follow-up cleanup.
+
+### Added
+
+- **mDNS auto-discovery.** New `autoDiscover` (and optional `discoveryTimeout`) config flag. When enabled, the plugin browses `_esphomelib._tcp` and creates accessories for any discovered ESPHome device that exposes a `Climate` entity. Manually configured devices in `devices[]` continue to work and are required for encrypted devices (the Noise key is not broadcast over mDNS).
+- **Multi-entity per accessory.** A single ESPHome device's `Climate` + `Sensor` + `Switch` + `Button` entities are now bundled into one HomeKit accessory with multiple services. Previously only the climate entity was used; everything else from the device was silently dropped.
+- **`Service.HumiditySensor`** when the ESPHome device exposes a `*humidity*` sensor entity. Hide with `disableHumiditySensor` (global) or `devices[].disableHumiditySensor` (per device) — useful for ACs that report a fake `0 %` because no probe is fitted.
+- **`Service.TemperatureSensor` (outdoor)** when an `*outdoor*temp*` sensor is exposed. Hide with `disableOutdoorTempSensor`.
+- **Eve.Energy power consumption** characteristic (`E863F10D-...`) on the climate accessory when a `*power*` sensor is exposed. Includes optional `fakegato-history` integration for Eve.app graphs. Hide with `disablePowerSensor`.
+- **Beeper Switch** when the device exposes a `Switch` entity matching `*beeper*`. Hide with `disableBeeperSwitch`.
+- **Display Toggle Switch** when the device exposes a `Button` entity matching `*display*`. Auto-resets to off after each tap (the underlying ESPHome entity is a stateless Button). Hide with `disableDisplaySwitch`.
+- **DRY-mode Switch.** Companion `Service.Switch` on devices that advertise `ESP_MODE.DRY (5)`. Toggling ON sets the AC to DRY mode; toggling OFF restores the previous primary mode (HEAT/COOL/AUTO), or OFF if the device had no prior primary mode. Hide with `disableDryMode`.
+- **FAN_ONLY-mode Switch.** Same pattern as DRY for `ESP_MODE.FAN_ONLY (4)`. Hide with `disableFanOnlyMode`.
+- **`StatusActive` and `StatusFault` characteristics** on the climate service. Mirror the ESPHome client's connected/disconnected events: `StatusFault` flips to `GENERAL_FAULT` (red badge in HomeKit) when the device drops, and back to `NO_FAULT` on reconnect.
+- **`FirmwareRevision` accessory characteristic** populated from the ESPHome `deviceInfo.esphomeVersion` field.
+- **`lib/discovery.js`** — wraps the upstream `Discovery` class with a Promise-based API plus `prettyNameFromHostname` helper for naming auto-discovered devices.
+- **`lib/classifyEntity.js`** — pure helper that maps ESPHome entities to HomeKit-service slots by name/objectId pattern. Unit-tested.
+- **`lib/eve.js`** — Eve.Energy custom characteristic factory with HAP-NodeJS Formats/Perms fallback chain (handles HB 2.0 / HAP-NodeJS 2.x removal of static accessors).
+- **`fakegato-history` dependency** at `^0.6.7`. Best-effort at runtime — `lib/DeviceAccessory.js` `try/catch`-wraps the `require` and disables history quietly if the module is unavailable.
+- **`jest` test suite (78 tests).** Covers `lib/state.js` (mode mappers, fan conversions, swing defaults, capability checks), `lib/classifyEntity.js` (entity classification + bundling), and `lib/discovery.js` (hostname formatting + dedupe). `npm test` runs them.
+- **`pickAutoMode`, `supportsCool`, `supportsHeat`** helpers in `lib/state.js` — encode the rule "AUTO and HEAT_COOL are interchangeable for HomeKit's AUTO target state".
+- **`CLAUDE.md`, `AGENTS.md`, `ROADMAP.md`, `QA_TESTS.md`, this `CHANGELOG.md`** — full warmup-style doc set covering project memory, milestone plan, manual pre-release checklist.
+- **GitHub Actions CI workflow** (`.github/workflows/ci.yml`) — lint + unit tests + smoke on Node 18.20.4, 20.15.1, 22.x, 24.x for every push and PR.
+- **GitHub Actions release workflow** (`.github/workflows/release.yml`) — tag-driven (`v*`); verifies the tag matches `package.json` version, runs lint + tests, publishes to npm with `--provenance`, extracts release notes from CHANGELOG and creates a GitHub Release.
+
+### Fixed
+
+- **`HEAT_COOL (1)` vs `AUTO (6)` confusion.** The original code only handled ESPHome mode 6 (`AUTO`) when filtering valid HomeKit target states and when sending the AUTO command. Many AC devices (visible in real SLWF-01Pro web UIs) advertise `HEAT_COOL` (1) instead — so the HomeKit AUTO button would either not appear or send a mode the device couldn't honor. `pickAutoMode(supportedModesList)` now picks `AUTO` when supported, falling back to `HEAT_COOL`. `supportsCool/Heat` also recognize `HEAT_COOL` as implying both directions.
+- **Multi-device commands could be lost.** `stateManager.js` used a module-level `sendTimeout` shared across every configured ESPHome device. The debounce timer is now per-device (`that._sendTimeout`).
+- **Crash on disconnected device.** `stateManager.sendState` referenced an undefined `log` symbol — every send to a disconnected device threw `ReferenceError: log is not defined` instead of returning a clean HomeKit "Not Responding". Now uses `that.log.error` and rejects with `HapStatusError(SERVICE_COMMUNICATION_FAILURE)`.
+- **Stacked `connected`/`disconnected` listeners.** Listeners were attached *inside* the `entity.once('state', …)` callback in `esphome.js`. Now attached at platform scope, exactly once per `Client`. Initialization is gated on the `Client` `initialized` event so the entire entity bundle is available, not just whatever happened to arrive first.
+- **Plugin registered as a static platform instead of dynamic.** `api.registerPlatform(name, alias, Class)` was missing the trailing `true` flag. Added.
+- **`package.json` `repository.url` pointed to upstream.** Would break npm sigstore provenance on publish (HTTP 422). Now points to the fork's GitHub URL.
+- **`HeaterCooler.updateState` mutated incoming state** when clamping `targetTemperature`. Replaced with a non-mutating `clampTargetTemperature(value)` helper.
+- **Lint errors.** Two indentation mismatches in the original `lib/HeaterCooler.js` resolved; the file itself was retired in favour of `lib/DeviceAccessory.js`.
+
+### Fixed (post-review cleanup)
+
+Three independent code-review passes (general bug-hunt, HomeKit/ESPHome semantics, docs/handoff) surfaced the following correctness issues that were addressed before tagging 0.1.0:
+
+- **`climateCommandService(that.state)` was sending all state fields including stale `target_temperature_low/high = 0` and `legacy_away = false` on every command.** Critical for HEAT_COOL-mode devices, where this would actively overwrite the device's heat/cool band to `[0, 0]` on each user interaction. `lib/stateManager.js` now builds a clean payload with only the fields actually mutated by the current `.onSet` cycle (tracked via `markDirty`), plus the entity `key`.
+- **`pruneOrphanedAccessories` ran with an empty live-host set when auto-discovery returned zero devices.** A transient mDNS failure (Wi-Fi blip, router reboot) would silently unregister every cached HomeKit accessory — losing room assignments and automations. The plugin now keeps cached accessories when discovery fails (with a clear error log) and only prunes when it has positive evidence the device list is genuinely empty.
+- **`Active` characteristic initialised to ON for a freshly-loaded OFF device** because `state.mode === undefined` made `state.mode !== 0` evaluate to `true`. Replaced with an explicit `isModeActive(mode)` helper.
+- **Empty `validValues` array for HeaterCooler `TargetHeaterCoolerState`** when a device's `supportedModesList` had no HEAT/COOL/AUTO/HEAT_COOL primary modes (e.g. DRY+FAN_ONLY-only). HAP-NodeJS rejects empty validValues. Now falls back to `[AUTO]` so the accessory still serializes.
+- **`client.once('initialized')` skipped re-initialization** if the user added a new ESPHome entity (fresh YAML flash) and the device reconnected. Switched to `client.on('initialized')` with a per-client `initialized` flag.
+- **ESPHome's `missingState` flag was ignored** — a sensor reporting `missingState: true` (no reading available) decoded to `state.state = 0` and the plugin published `0%`/`0°C`/`0W`. New `readSensorValue` helper checks `missingState` and `Number.isFinite` before returning a value.
+- **DRY/FAN_ONLY OFF-toggle defaulted to COOL** even on a fresh device that had never been in a primary mode. Now snapshots `accessory.context.preSupplementaryMode` when entering DRY/FAN_ONLY and falls back to OFF if no prior primary mode was recorded.
+- **Display Toggle Switch fired on both ON and OFF taps.** The HomeKit Switch's `.onSet(value)` handler ignored `value` and called `Button.push()` unconditionally. Now: if `!value`, return early; the toggle is one-way (auto-resets to off after 250 ms).
+- **HumiditySensor add/remove subtype mismatch.** `addService(..., 'humidity')` used a subtype, but `getService(...)` lookup didn't — could match the wrong service if multiple were ever present. Now uses `getServiceById(..., 'humidity')` consistently with the other optional services.
+- **`fakegato-history`'s reaction to NaN sensor data.** Same `readSensorValue` guard prevents NaN from making it into Eve.app's history series.
+- **`getCharacteristic(eve.CurrentPowerConsumption)` already auto-adds.** The `existing || addCharacteristic(...)` ternary in `attachPowerCharacteristic` was dead code (the second branch could never run). Cleaned up.
+- **`SwingMode` and `RotationSpeed` setters** now dedupe identical values (early-resolve when target equals current) — matches the existing pattern used by `Active`/`TargetHeaterCoolerState`/temperature thresholds, avoids spurious roundtrips.
+- **`setConnectedStatus` race during accessory construction.** Wrapped in try/catch + service-presence guard, so a disconnect during the brief window between `'initialized'` and the constructor finishing won't crash the platform.
+- **Unused `TotalConsumption` Eve characteristic** removed from `lib/eve.js` — kWh totalisation isn't implemented and the dead export was misleading.
+
+### Changed
+
+- **`lib/HeaterCooler.js` retired; replaced by `lib/DeviceAccessory.js`.** The class is now a multi-service composer rather than a climate-only wrapper. Service-binding methods are split: `addClimateService`, `addOptionalSensorServices`, `addOptionalSwitchServices`, `addModeSwitchServices`, `removeDisabledServices`. Cached service cleanup is honored — disabling a flag on a previously-enabled service unregisters the service on next launch.
+- **`lib/esphome.js` rewritten async.** Orchestrates manual `devices[]` + auto-discovered devices (deduped by host); spawns a `Client` per device; waits for the Client's `initialized` event; routes connected/disconnected events into `setConnectedStatus(bool)` on the accessory.
+- **`fanSpeedToFanMode` / `fanModeToSpeed` are inverses.** Previously the conversion only existed for HomeKit-set → ESPHome direction; the reverse was inlined ad-hoc and inconsistent. Both directions live in `lib/state.js` now.
+- **`engines.node` raised to `^18.20.4 || ^20.15.1 || ^22.0.0 || ^24.0.0`.** Old `>=18.0.0` allowed long-EOL Node 18 patch releases.
+- **`engines.homebridge` widened to `^1.8.0 || ^2.0.0`.**
+- **`displayName` added to `package.json`** as "Homebridge SLWF-01Pro / ESPHome AC".
+- **`package.json` `description`** updated from inherited upstream wording to mention SLWF-01Pro and the multi-entity feature set.
+- **`package.json` `funding`** block (PayPal / Patreon / Ko-fi pointing at the original author) removed; donations should not flow to a maintainer who isn't shipping the fork.
+- **`package.json` `files`** array added to scope what `npm publish` ships — prevents `test/`, `CLAUDE.md`, `ROADMAP.md`, `QA_TESTS.md`, and `.claude/` from leaking into the published tarball.
+- **`.gitignore`** replaced with a minimal Node-only ignore set; the inherited Xcode/iOS boilerplate from upstream is gone.
+- **npm package renamed** from inherited `homebridge-esphome-ac` to **`homebridge-slwf-01pro`** to avoid colliding with the upstream package on the npm registry. The Homebridge platform identifier in users' `config.json` (`"platform": "ESPHomeAC"`) is unchanged for migration compatibility — only the install command differs (`sudo npm uninstall -g homebridge-esphome-ac && sudo npm install -g homebridge-slwf-01pro`).
+- **`PLUGIN_NAME` constant in `index.js`** updated to match the new npm name. Existing users of upstream `homebridge-esphome-ac@0.0.4` will see their cached accessories re-pair on first launch (the HomeKit UUIDs are still derived from `entity.config.uniqueId` so they reattach to the same Home app tile).
+- **LICENSE** preserves the original 2020 Nitay Ben Zvi MIT copyright + adds the 2026 Karol Nowacki fork copyright.
+- **README rewritten** with SLWF-01Pro device context (hardware revisions, supported AC brands, ESPHome-specific quirks like intake-mounted sensor inaccuracy and `midea_ac.follow_me`), full configuration reference, troubleshooting, and child-bridge recommendation.
+
+### Internal
+
+- `Service` and `Characteristic` lookups hoisted to module scope in `DeviceAccessory.js` (set once on first construction).
+- `index.js` `log.easyDebug` now uses `Array#map` + `Array#join` instead of `Array#reduce` string concatenation; mixed string + object arguments stringify cleanly.
+- `SET_DEBOUNCE_MS` / `ACTIVE_BATCH_MS` / `TEMP_BATCH_MS` are named constants instead of magic numbers.
+
+---
+
+## [0.0.4] — pre-fork (upstream `nitaybz/homebridge-esphome-ac`)
+
+The point at which this fork was taken. Upstream history below is preserved for context.
+
+### Fixed (in upstream)
+
+- Bug fixes (commit `7ce4654`).
+- `set` commands changed to return promises (commit `5a1930d`) — switched from `.on('set', cb)` to `.onSet(async)`.
+- Removed stray `%` from swing log line (commit `0cf6d7d`).
+- Stable per-entity unique id used for HomeKit UUID instead of host (commit `f4461f0`).
+
+### Initial release (upstream)
+
+- ESPHome native-API integration via `@2colors/esphome-native-api`.
+- HomeKit `Service.HeaterCooler` exposing Active, Current/TargetHeaterCoolerState, CurrentTemperature, Heating/CoolingThresholdTemperature, SwingMode, RotationSpeed.
+- Auto-discovery of climate-entity capabilities (modes/fan modes/swing modes/visual temp range).
+- `config.schema.json` for the Homebridge UI.
+- One platform-level `debug` flag.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Nitay Ben Zvi (original homebridge-esphome-ac)
+Copyright (c) 2026 Karol Nowacki (homebridge-slwf-01pro fork)
+
+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/README.md

@@ -0,0 +1,266 @@
+# homebridge-SLWF-01Pro
+
+[Homebridge](https://homebridge.io) plugin for the **[SLWF-01Pro Wi-Fi dongle](https://smartlight.me/smart-home-devices/wifi-devices/wifi-dongle-air-conditioners-midea-idea-electrolux-for-home-assistant)** flashed with ESPHome — exposes the AC it's plugged into as a HomeKit `HeaterCooler` accessory with full mode, fan-speed and swing control.
+
+The SLWF-01Pro is a Wi-Fi dongle from **[SMLIGHT](https://smartlight.me)** (Ukraine) that drops into the proprietary serial Wi-Fi port on Midea-protocol air conditioners — replacing the OEM Tuya/SmartLife stick. Hardware revisions in the wild: **v1.1**, **v1.2** (ESP8266) and **v2.1** (ESP32); pinouts differ between revisions. Once flashed with [ESPHome](https://esphome.io) (typically the [`midea_ac`](https://esphome.io/components/climate/midea.html) component) the dongle exposes the AC as a `Climate` entity over the ESPHome native API — this plugin bridges that entity into HomeKit.
+
+This is a **maintained fork** of [`homebridge-esphome-ac`](https://github.com/nitaybz/homebridge-esphome-ac) by nitaybz, focused on the SLWF-01Pro use case: bug fixes, cleanup, and longer-term polish around multi-device reliability.
+
+## Why this fork exists
+
+The upstream plugin works for single-device setups but has a few sharp edges that bite multi-AC households (the typical SLWF-01Pro buyer often has multiple Midea/Electrolux units). The fork addresses correctness *and* expands HomeKit coverage:
+
+- **HEAT_COOL devices got no AUTO button.** Many SLWF-01Pro / Midea ACs advertise mode `HEAT_COOL` (1) instead of `AUTO` (6). The original plugin only checked for mode 6 → HomeKit AUTO didn't appear. The fork picks whichever mode the device supports.
+- **Wire-format payload was leaky.** The original sent the *entire* climate-state object with every command, including stale `target_temperature_low/high = 0`. On HEAT_COOL devices this overwrites the heat/cool band on every interaction. The fork builds a clean payload of only the fields you actually changed.
+- **Multi-device command coalescing.** A module-level send timeout meant changing one AC could cancel a pending command on another. Each AC now owns its own debouncer.
+- **Crash on disconnected device.** The upstream `device disconnected` error path referenced an undefined `log` symbol → `ReferenceError` instead of a clean HomeKit error. Fixed.
+- **Auto-discovery via mDNS** — listed `_esphomelib._tcp` services are picked up automatically; you don't need to type six IP addresses for six ACs.
+- **Multi-entity bundling** — humidity, outdoor temperature, power consumption, beeper, display toggle, DRY, and FAN_ONLY all show up in HomeKit when the device exposes them.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full restoration story.
+
+## Supported devices
+
+Anything that publishes a `Climate` entity over the ESPHome native API will work. The intended target is the SLWF-01Pro itself, but the plugin is hardware-agnostic — any ESPHome `climate:` component (e.g. an ESP32 with [`midea_ac`](https://esphome.io/components/climate/midea.html) directly soldered) will be picked up.
+
+| AC brand families known to work with SLWF-01Pro | Notes |
+|---|---|
+| **Midea**, Idea, Electrolux, Bosch, Beko, Neoclima | Manufacturer's primary tested set; all Midea-protocol mini-splits |
+| Senville (Leto), Yitahome, Mr. Cool, AUX | Other Midea-platform rebadges |
+| Alpine, Pioneer, Samsung, Toshiba, Zanussi | ~30 brands total — see [smartlight.me](https://smartlight.me/smart-home-devices/wifi-devices/wifi-dongle-air-conditioners-midea-idea-electrolux-for-home-assistant) for the full list |
+| Newer 2024+ AC firmwares with proprietary protocols | May not work — check the manufacturer's compatibility notes before buying |
+
+DRY and FAN_ONLY ESPHome modes are surfaced as **companion `Switch` services** ("AC Dry", "AC Fan Only") next to the main `HeaterCooler` tile. Toggling one ON puts the AC into that mode; toggling OFF restores the previous primary mode (HEAT/COOL/AUTO). Hide via `disableDryMode` / `disableFanOnlyMode`.
+
+ESPHome's **custom fan modes** (`silent`, `turbo` on Midea) and **presets** (`eco`, `boost`, `sleep`, `away`) are not yet surfaced — the plugin only handles the standard fan-modes list. See [ROADMAP.md](ROADMAP.md).
+
+## Install
+
+```bash
+sudo npm install -g homebridge-slwf-01pro
+```
+
+Or from the Homebridge UI: search for **homebridge-slwf-01pro** 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-SLWF-01Pro#<sha>
+```
+
+## Configuration
+
+The simplest config — auto-discover everything on the local network:
+
+```jsonc
+{
+  "platforms": [
+    {
+      "platform": "ESPHomeAC",
+      "name": "ESPHomeAC",
+      "autoDiscover": true
+    }
+  ]
+}
+```
+
+Or fully manual (required for encrypted devices and any device not on the same broadcast domain):
+
+```jsonc
+{
+  "platforms": [
+    {
+      "platform": "ESPHomeAC",
+      "name": "ESPHomeAC",
+      "debug": false,
+      "devices": [
+        {
+          "name": "Living Room AC",
+          "host": "192.168.1.120",
+          "port": 6053,
+          "encryptionKey": "",
+          "disableHumiditySensor": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+You can mix both — listed devices in `devices[]` take precedence; auto-discovered devices are added on top.
+
+### Platform-level keys
+
+| Key | Required | Default | Notes |
+|---|---|---|---|
+| `platform` | yes | — | Must be exactly `"ESPHomeAC"` (the platform identifier — same as the upstream plugin so existing configs migrate without edits) |
+| `name` | no | `ESPHomeAC` | Display name in Homebridge logs |
+| `debug` | no | `false` | Surface ESPHome state-change chatter to the main log instead of `log.debug` |
+| `autoDiscover` | no | `false` | mDNS-browse for ESPHome devices on the local network and create accessories automatically. Encrypted devices still need a manual `devices[]` entry — the Noise key is not broadcast. |
+| `discoveryTimeout` | no | `5` | Seconds to wait for mDNS responses before continuing. |
+| `disableHumiditySensor` | no | `false` | Hide the HumiditySensor service for **every** device (e.g. ACs that report a fake `0 %` because no probe is fitted). |
+| `disableOutdoorTempSensor` | no | `false` | Hide the outdoor TemperatureSensor service. |
+| `disablePowerSensor` | no | `false` | Hide the Eve.Energy CurrentPowerConsumption characteristic. |
+| `disableBeeperSwitch` | no | `false` | Hide the Beeper Switch service. |
+| `disableDisplaySwitch` | no | `false` | Hide the Display Toggle Switch service. |
+| `disableDryMode` | no | `false` | Hide the DRY mode Switch service. |
+| `disableFanOnlyMode` | no | `false` | Hide the FAN_ONLY mode Switch service. |
+| `devices` | no | `[]` | Manual list of ESPHome devices. Required for encrypted devices; optional otherwise if `autoDiscover: true`. |
+
+### Per-device keys (under `devices[]`)
+
+| Key | Required | Default | Notes |
+|---|---|---|---|
+| `name` | yes | — | Display name in HomeKit |
+| `host` | yes | — | IP address or hostname of the SLWF-01Pro / ESPHome device |
+| `port` | no | `6053` | ESPHome native API port |
+| `encryptionKey` | no | `""` | Base64 ESPHome `api: encryption` key, if set in the device's YAML |
+| `disableHumiditySensor` | no | `false` | Per-device override; if true, hides the HumiditySensor for **this** device only. |
+| `disableOutdoorTempSensor` | no | `false` | Per-device override |
+| `disablePowerSensor` | no | `false` | Per-device override |
+| `disableBeeperSwitch` | no | `false` | Per-device override |
+| `disableDisplaySwitch` | no | `false` | Per-device override |
+| `disableDryMode` | no | `false` | Per-device override |
+| `disableFanOnlyMode` | no | `false` | Per-device override |
+
+Per-device disable flags **override** the platform-wide flag (logical OR — `device[key] || platform[key]`). The platform-wide flag turns the service off for every device; the per-device flag turns it off for just that one. There's no way to enable a service that's globally disabled.
+
+The plugin auto-discovers the climate entity's capabilities (supported modes, fan modes, swing modes, visual min/max temperatures, target step) directly from ESPHome — no model-specific config required.
+
+`config.schema.json` provides a form-based editor in the Homebridge UI.
+
+## Recommended: enable Child Bridge
+
+If you have **two or more** SLWF-01Pro dongles, run this plugin in a Homebridge **Child Bridge**. ESPHome devices on Wi-Fi can blip out for a few seconds during router restarts; isolating the plugin means a hung reconnect can't block your other accessories.
+
+In the Homebridge UI: **Plugins** tab → click the gear icon on the plugin → **Bridge Settings** → enable **Child Bridge**. Restart when prompted.
+
+## What ends up in HomeKit
+
+Per ESPHome device, all of these services land on a single HomeKit accessory if the device exposes the matching entity (and the corresponding `disable*` flag is `false`):
+
+| HomeKit service | Source ESPHome entity | Disable flag |
+|---|---|---|
+| `Service.HeaterCooler` (mandatory) | `Climate` entity | — |
+| `Service.HumiditySensor` | Sensor matching `*humidity*` | `disableHumiditySensor` |
+| `Service.TemperatureSensor` (outdoor) | Sensor matching `*outdoor*temp*` | `disableOutdoorTempSensor` |
+| Eve.Energy `CurrentPowerConsumption` (W) on the AC accessory | Sensor matching `*power*` | `disablePowerSensor` |
+| `Service.Switch` "Beeper" | Switch matching `*beeper*` | `disableBeeperSwitch` |
+| `Service.Switch` "Display" | Button matching `*display*` (auto-resets after press) | `disableDisplaySwitch` |
+| `Service.Switch` "Dry" | Climate device's `DRY` mode | `disableDryMode` |
+| `Service.Switch` "Fan Only" | Climate device's `FAN_ONLY` mode | `disableFanOnlyMode` |
+| `StatusActive` + `StatusFault` (on the climate service) | Mirrors ESPHome client connect/disconnect | — (always on) |
+
+Entities the plugin deliberately ignores: Wi-Fi RSSI, Uptime, Factory Reset (dangerous to expose).
+
+## Behaviour
+
+### Modes
+
+The HomeKit `HeaterCooler` accessory uses three modes; this plugin maps them as follows:
+
+| HomeKit | ESPHome `ClimateMode` | What happens |
+|---|---|---|
+| **Off** (Active=0) | `OFF` (0) | AC turns off; HomeKit remembers the previous mode for the next "On" tap |
+| **Heat** | `HEAT` (3) | AC switches to heating mode |
+| **Cool** | `COOL` (2) | AC switches to cooling mode |
+| **Auto** | `AUTO` (6) | AC switches to auto / heat-cool mode |
+
+The mode-list shown to HomeKit is filtered to the modes ESPHome actually advertises (`supportedModesList`), so a cooling-only AC won't show a Heat button.
+
+### Temperature
+
+HomeKit sends one of two temperature characteristics depending on mode: `CoolingThresholdTemperature` (in Cool / Auto) or `HeatingThresholdTemperature` (in Heat / Auto). Both currently set the same single `target_temperature` ESPHome field — the plugin doesn't yet use the device's two-point `target_temperature_low`/`target_temperature_high` even when supported. See [ROADMAP.md](ROADMAP.md).
+
+Slider drags are debounced — the plugin sends one ESPHome command 600 ms after you stop, not one per tick.
+
+### Fan speed
+
+HomeKit's `RotationSpeed` (0–100%) is split evenly across the device's `supportedFanModesList`. So if your AC supports `[LOW, MEDIUM, HIGH]`, 1–33% maps to LOW, 34–66% to MEDIUM, 67–100% to HIGH. The `AUTO` fan mode (if supported) is selected when you set rotation speed to 0.
+
+### Swing
+
+If the device advertises any swing mode beyond OFF, a HomeKit Swing toggle is exposed. The plugin chooses the most useful swing direction at startup (BOTH > VERTICAL > HORIZONTAL) and the toggle flips between that direction and OFF.
+
+## Migration
+
+If you're moving from the upstream `homebridge-esphome-ac`:
+
+```bash
+sudo npm uninstall -g homebridge-esphome-ac
+sudo npm install -g homebridge-slwf-01pro
+sudo systemctl restart homebridge   # or: hb-service restart
+```
+
+**Your `config.json` does not need changes.** The platform identifier (`"platform": "ESPHomeAC"`) is unchanged for compatibility — only the npm package name differs.
+
+If accessories appear duplicated after the migration, clear Homebridge's cached accessories from the UI (Settings → Remove Single Cached Accessory) for the orphaned ones from the old plugin. The new plugin will re-pair them automatically on the next restart with stable UUIDs derived from each device's ESPHome `entity.config.uniqueId`.
+
+## Known SLWF-01Pro quirks
+
+These are device-side issues, not plugin bugs — listed here so you know what to expect:
+
+- **Intake-mounted temperature sensor reads warm/cold air, not room temp.** HomeKit will show a value that's a few degrees off the actual room. Mitigation: ESPHome's [`midea_ac.follow_me`](https://esphome.io/components/climate/midea.html) action pushes an external Home Assistant sensor reading into the AC, but it's a Home-Assistant-only feature and (on some Senville/Midea units) requires a small hardware mod soldering IO13 to the display board's "Rec 1 OUT" pin.
+- **Pinout differs between v1.1, v1.2 and v2.1** of the dongle. Wrong YAML for your hardware revision means no UART communication. Check the SMLIGHT product page for the matching firmware before flashing.
+- **Outdoor temperature and humidity setpoint** are model-specific (e.g. Midea Mission II doesn't expose them); expect them to be missing on most installs.
+- **Newer Midea firmwares** with proprietary key exchange may refuse to talk to the dongle. SMLIGHT's compatibility list is the source of truth.
+
+## Troubleshooting
+
+### Plugin starts but the AC tile in HomeKit is "Not Responding"
+Check that the SLWF-01Pro is reachable from the Homebridge host (`ping <host>` and `nc -vz <host> 6053`). The plugin connects on `didFinishLaunching` and reconnects every 5 s if the device drops; if you see no `<name> client connected` line followed by `Initialized "<name>" with N mapped entit(y|ies)` in the log within a minute, ESPHome isn't accepting the connection. Common causes: wrong `encryptionKey`, firewall, ESPHome `api:` block missing.
+
+### "ESPHome device" appears but no temperature shown
+ESPHome may not have published the initial `state` event yet. Wait 30 s; if still empty, restart the SLWF-01Pro.
+
+### Multi-AC: changing one AC's setting cancels another's
+This was a real bug in upstream `homebridge-esphome-ac@0.0.4` (module-level send timeout, shared across all devices). Fixed in this fork's first release.
+
+### My AC has no humidity probe but HomeKit shows 0 %
+Set `disableHumiditySensor: true` (either platform-wide or just under that device's `devices[]` entry). The HumiditySensor service will be removed on the next restart.
+
+### Auto-discovery doesn't see one of my ACs
+Likely causes: (1) the device has `api: encryption: key:` set in its ESPHome YAML, in which case mDNS doesn't broadcast the Noise key — add it manually to `devices[]`. (2) The device is on a different VLAN/subnet that blocks mDNS. (3) ESPHome's `mdns:` block is disabled. Quickest fix: list it manually in `devices[]`.
+
+### HomeKit AUTO button missing on a device that supports auto mode
+Your device probably advertises `HEAT_COOL` (mode 1) instead of `AUTO` (mode 6). Both are now handled equivalently as of this fork's first release; if you're on upstream `homebridge-esphome-ac@0.0.4`, this was the bug.
+
+### Debug logs
+Set `"debug": true` in the platform config — every state change and outgoing command will surface in the main log.
+
+## Development
+
+```bash
+git clone https://github.com/nookied/homebridge-SLWF-01Pro.git
+cd homebridge-SLWF-01Pro
+npm install
+npm run lint                                  # ESLint
+npm test                                      # Jest — 78 unit tests
+node -e "require('./index.js')"               # smoke test (loads cleanly)
+```
+
+See [QA_TESTS.md](QA_TESTS.md) for the manual pre-release checklist and [ROADMAP.md](ROADMAP.md) for what's planned next.
+
+## Releasing
+
+After the pre-release checklist in [QA_TESTS.md](QA_TESTS.md) passes:
+
+```bash
+npm version 0.1.0                              # bumps package.json + creates v0.1.0 tag
+git push --follow-tags                         # pushes commit + tag
+npm pack --dry-run                             # sanity-check tarball contents
+gh release create v0.1.0 --notes-from-tag      # GitHub Release from tag message
+```
+
+`package.json` has a `files` array, so `npm publish` ships only `index.js`, `lib/`, `config.schema.json`, `config-sample.json`, `LICENSE`, `README.md`, `CHANGELOG.md`. Internal docs (`CLAUDE.md`, `ROADMAP.md`, `QA_TESTS.md`, `test/`) stay out of the published tarball.
+
+## License
+
+[MIT](LICENSE). Copyright 2020 Nitay Ben Zvi (original) + 2026 Karol Nowacki (this fork). The MIT license is preserved from the original.
+
+## Credits
+
+- **[nitaybz](https://github.com/nitaybz)** — original `homebridge-esphome-ac` plugin (2020), the basis for this fork.
+- **[smartlight.me](https://smartlight.me)** — designs and ships the SLWF-01Pro hardware + ESPHome firmware.
+- **[ESPHome](https://esphome.io)** — the firmware and native-API protocol the plugin speaks.
+- **[@2colors/esphome-native-api](https://github.com/2colors/esphome-native-api)** — Node.js client for the ESPHome native API.

package/config-sample.json

@@ -0,0 +1,31 @@
+{
+  "bridge": {
+    "name": "Homebridge",
+    "username": "CD:22:3D:E3:CE:30",
+    "port": 51826,
+    "pin": "031-45-154"
+  },
+
+  "description": "Sample config for the homebridge-SLWF-01Pro fork. Pick auto-discovery OR manual devices, or both.",
+  "platforms": [
+    {
+      "platform": "ESPHomeAC",
+      "name": "ESPHomeAC",
+      "debug": false,
+      "autoDiscover": true,
+      "discoveryTimeout": 5,
+      "disableHumiditySensor": false,
+      "devices": [
+        {
+          "name": "Living Room AC",
+          "host": "192.168.1.120",
+          "port": 6053,
+          "encryptionKey": "",
+          "disableHumiditySensor": true
+        }
+      ]
+    }
+  ],
+
+  "accessories": []
+}

package/config.schema.json

@@ -0,0 +1,215 @@
+{
+  "pluginAlias": "ESPHomeAC",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Homebridge plugin for ESPHome AC controllers (SLWF-01Pro Wi-Fi dongle and other ESPHome `Climate` entities). Supports auto-discovery, humidity / outdoor-temperature / power sensors, beeper / display switches, and DRY / FAN_ONLY mode tiles.",
+  "footerDisplay": "Original by @nitaybz; SLWF-01Pro fork by @nookied.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Plugin Name (for logs)",
+        "type": "string",
+        "default": "ESPHomeAC",
+        "required": false
+      },
+      "debug": {
+        "title": "Enable Debug Logs",
+        "description": "Surface ESPHome state-change chatter to the main log (otherwise sent to log.debug).",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "autoDiscover": {
+        "title": "Auto-discover ESPHome devices via mDNS",
+        "description": "Browses _esphomelib._tcp on the local network and adds any ESPHome devices with a Climate entity. Only works for unencrypted ESPHome API. Manually configured devices in the list below take precedence and are required for encrypted devices.",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "discoveryTimeout": {
+        "title": "Discovery timeout (seconds)",
+        "type": "integer",
+        "default": 5,
+        "minimum": 2,
+        "maximum": 30,
+        "required": false,
+        "condition": { "functionBody": "return model.autoDiscover === true;" }
+      },
+      "disableHumiditySensor": {
+        "title": "Hide Humidity sensor service (for ACs without a real humidity probe)",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "disableOutdoorTempSensor": {
+        "title": "Hide Outdoor Temperature sensor service",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "disablePowerSensor": {
+        "title": "Hide Power Usage characteristic (Eve.Energy)",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "disableBeeperSwitch": {
+        "title": "Hide Beeper switch",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "disableDisplaySwitch": {
+        "title": "Hide Display Toggle switch",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "disableDryMode": {
+        "title": "Hide DRY mode switch",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "disableFanOnlyMode": {
+        "title": "Hide FAN_ONLY mode switch",
+        "type": "boolean",
+        "default": false,
+        "required": false
+      },
+      "devices": {
+        "type": "array",
+        "required": false,
+        "items": {
+          "title": "Devices",
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Display name in HomeKit",
+              "type": "string",
+              "required": true
+            },
+            "host": {
+              "title": "Hostname or IP address",
+              "type": "string",
+              "required": true
+            },
+            "port": {
+              "title": "ESPHome native API port",
+              "type": "integer",
+              "default": 6053,
+              "minimum": 1,
+              "maximum": 65535,
+              "required": false
+            },
+            "encryptionKey": {
+              "title": "ESPHome API Noise encryption key (base64)",
+              "type": "string",
+              "required": false
+            },
+            "disableHumiditySensor": {
+              "title": "Hide Humidity sensor for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            },
+            "disableOutdoorTempSensor": {
+              "title": "Hide Outdoor Temperature for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            },
+            "disablePowerSensor": {
+              "title": "Hide Power Usage for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            },
+            "disableBeeperSwitch": {
+              "title": "Hide Beeper switch for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            },
+            "disableDisplaySwitch": {
+              "title": "Hide Display Toggle for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            },
+            "disableDryMode": {
+              "title": "Hide DRY mode switch for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            },
+            "disableFanOnlyMode": {
+              "title": "Hide FAN_ONLY mode switch for this device",
+              "type": "boolean",
+              "default": false,
+              "required": false
+            }
+          }
+        }
+      }
+    }
+  },
+  "layout": [
+    { "key": "name" },
+    { "key": "debug" },
+    {
+      "type": "fieldset",
+      "title": "Auto-discovery",
+      "expandable": true,
+      "expanded": true,
+      "items": ["autoDiscover", "discoveryTimeout"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Global service toggles (apply to all devices)",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "disableHumiditySensor",
+        "disableOutdoorTempSensor",
+        "disablePowerSensor",
+        "disableBeeperSwitch",
+        "disableDisplaySwitch",
+        "disableDryMode",
+        "disableFanOnlyMode"
+      ]
+    },
+    {
+      "key": "devices",
+      "type": "array",
+      "title": "Manual device list",
+      "description": "Optional. Required for encrypted ESPHome devices. Per-device toggles override the globals.",
+      "orderable": false,
+      "buttonText": "Add Device",
+      "expandable": true,
+      "expanded": false,
+      "items": [
+        "devices[].name",
+        "devices[].host",
+        "devices[].port",
+        "devices[].encryptionKey",
+        {
+          "type": "fieldset",
+          "title": "Per-device service toggles",
+          "expandable": true,
+          "expanded": false,
+          "items": [
+            "devices[].disableHumiditySensor",
+            "devices[].disableOutdoorTempSensor",
+            "devices[].disablePowerSensor",
+            "devices[].disableBeeperSwitch",
+            "devices[].disableDisplaySwitch",
+            "devices[].disableDryMode",
+            "devices[].disableFanOnlyMode"
+          ]
+        }
+      ]
+    }
+  ]
+}