homebridge-slwf-01pro 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,71 @@ This package is a maintained fork of [`homebridge-esphome-ac`](https://github.co
 
 ---
 
+## [0.4.0] — 2026-05-06
+
+Naming cleanup. User-visible "ESPHome AC" / "ESPHomeAC" branding is now consistently **SLWF-01Pro**; technical references to the underlying ESPHome protocol (native API, mDNS service, Climate entity type) remain accurate where they describe the wire format the plugin speaks.
+
+### Breaking
+
+- **No config breakage.** Platform identifier (`SLWFOnePro`) and npm name (`homebridge-slwf-01pro`) are unchanged from 0.3.x. Existing configs and HomeKit pairings continue to work.
+- Internal class `ESPHomeAC` in `index.js` renamed to `SLWFOnePro`. Visible only in stack traces.
+
+### Changed
+
+- **`package.json` `displayName`** simplified from "Homebridge SLWF-01Pro / ESPHome AC" to **"Homebridge SLWF-01Pro"**. Cleaner in the Homebridge UI plugin browser and matches the npm package name.
+- **`package.json` `description`** rewritten to lead with SLWF-01Pro and the SMLIGHT brand; ESPHome native API mentioned as the underlying protocol, not the headline product.
+- **`package.json` `keywords`** pruned: dropped `homebridge-esphome`, `homebridge-esphome-ac`, `esphome-ac` (upstream-related, not relevant for this fork's npm discoverability); kept `slwf`, `slwf-01pro`, `smlight`, AC-brand names; added `air-conditioner`.
+- **`config.schema.json`** copy refreshed:
+  - `headerDisplay` linked to the SMLIGHT product page; dropped "ESPHome `Climate` entities" framing in favour of "SLWF-01Pro Wi-Fi AC dongle"
+  - `footerDisplay` mentions ESPHome native API as the underlying protocol (correct framing for users who want to use the plugin with non-SLWF ESPHome devices)
+  - `debug.description` simplified: "device state-change chatter" instead of "ESPHome state-change chatter"
+  - `autoDiscover.title` changed to "Auto-discover SLWF-01Pro devices via mDNS"; description still references the actual `_esphomelib._tcp` mDNS service since that's the literal technical fact
+  - `port` and `encryptionKey` titles simplified ("Native API port", "API encryption key (base64)")
+  - Per-device toggles unchanged
+- **Log strings**:
+  - "Creating new ESPHome AC accessory" → "Creating new SLWF-01Pro accessory"
+  - "ESPHome device …reconnected" → "Device …reconnected"
+  - "No ESPHome devices configured…" → "No SLWF-01Pro / ESPHome devices configured…"
+  - "Browsing mDNS for ESPHome devices" / "Discovered N ESPHome devices" — kept (factually accurate; the mDNS service is `_esphomelib._tcp`).
+- **Accessory metadata** (Apple Home → ⓘ on each AC):
+  - Manufacturer fallback: `'ESPHome'` → `'SMLIGHT'` (only used when the device doesn't report its own manufacturer; SMLIGHT is the actual hardware vendor)
+  - Model fallback: `'ESPHome AC'` → `'SLWF-01Pro'`
+  - Real `deviceInfo.manufacturer` / `deviceInfo.model` from ESPHome still take precedence — these are only fallbacks when the device YAML doesn't provide them.
+- **`config-sample.json`** `name` field updated from `"ESPHomeAC"` to `"SLWF-01Pro"`.
+
+### Internal
+
+- All `[ESPHomeAC]` log prefixes will become `[SLWF-01Pro]` (or whatever you set in the `name` config field) once your `config.json`'s `name` is updated. Existing `name: "ESPHomeAC"` configs continue to work — the prefix just keeps the legacy value until you change it.
+- 120 unit tests still pass.
+
+---
+
+## [0.3.3] — 2026-05-06
+
+Fix the "config validation failed, you can still save your changes" warning shown by the Homebridge UI when editing the plugin's settings.
+
+### Fixed
+
+- **`config.schema.json` used the legacy per-property `"required": true/false` Homebridge convention**, which modern ajv (used by recent `homebridge-config-ui-x` versions) reports as a non-standard JSON Schema construct. Migrated to canonical JSON Schema:
+  - Removed all `"required": false` annotations (redundant — JSON Schema treats unlisted properties as optional by default).
+  - Replaced per-device `"required": true` on `name`/`host` with the parent-level `"required": ["name", "host"]` array on the device item schema.
+  - Added `minLength: 1` on required string fields so empty values are explicitly rejected (matches what the form validator was already enforcing).
+- **The `Devices` array's items had `"title": "Devices"` (plural)**, which the UI rendered as the same title for every entry; changed to `"Device"` (singular).
+
+### Added
+
+- **`test/unit/configSchemaValidation.test.js`** — runs the live `config.schema.json` through ajv against 20 sample configs, including the bundled `config-sample.json`, common partial configs, and explicit error cases (missing required fields, out-of-range numerics, wrong types). Catches schema regressions that would surface as validation warnings in the UI.
+  - 120 unit tests now pass (up from 100).
+- **`ajv` and `ajv-formats` as devDependencies** — vendored only for the test suite, not shipped in the runtime tarball.
+
+### Why the warning matters
+
+`homebridge-config-ui-x` validates saved config against the plugin's `config.schema.json` after every form save. When the schema is well-formed but uses non-standard JSON Schema constructs, ajv flags them and the UI shows the "config validation failed" warning even though the actual saved config is fine. The user could still save their changes, but the warning is alarming and obscures real validation problems (like a forgotten required field).
+
+This release modernizes the schema to canonical JSON Schema syntax, eliminating the false-positive warning. The ajv-based test suite ensures we don't regress.
+
+---
+
 ## [0.3.2] — 2026-05-06
 
 Config-schema polish + a regression-prevention test suite for the Homebridge UI form.

package/config-sample.json

@@ -6,11 +6,11 @@
     "pin": "031-45-154"
   },
 
-  "description": "Sample config for the homebridge-SLWF-01Pro fork. Pick auto-discovery OR manual devices, or both.",
+  "description": "Sample config for homebridge-slwf-01pro. Pick auto-discovery, manual devices, or both.",
   "platforms": [
     {
       "platform": "SLWFOnePro",
-      "name": "SLWFOnePro",
+      "name": "SLWF-01Pro",
       "debug": false,
       "autoDiscover": true,
       "discoveryTimeout": 5,

package/config.schema.json

@@ -2,30 +2,27 @@
   "pluginAlias": "SLWFOnePro",
   "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "Homebridge plugin for the **SMLIGHT SLWF-01Pro** Wi-Fi dongle and other ESPHome `Climate` entities. Supports mDNS auto-discovery, multi-entity bundling (humidity / outdoor temperature / power sensors, Beeper / Display switches, DRY / FAN_ONLY mode tiles).",
-  "footerDisplay": "Maintained fork by [@nookied](https://github.com/nookied/homebridge-SLWF-01Pro). Based on `homebridge-esphome-ac` by [@nitaybz](https://github.com/nitaybz/homebridge-esphome-ac).",
+  "headerDisplay": "Homebridge plugin for the **[SMLIGHT SLWF-01Pro](https://smartlight.me/smart-home-devices/wifi-devices/wifi-dongle-air-conditioners-midea-idea-electrolux-for-home-assistant)** Wi-Fi AC dongle. Supports mDNS auto-discovery on the local network and multi-entity bundling (humidity / outdoor temperature / power sensors, Beeper / Display switches, DRY / FAN_ONLY mode tiles).",
+  "footerDisplay": "Maintained by [@nookied](https://github.com/nookied/homebridge-SLWF-01Pro). Speaks the [ESPHome native API](https://esphome.io/components/api.html), so any ESPHome Climate device on the local network is also supported.",
   "schema": {
     "type": "object",
     "properties": {
       "name": {
         "title": "Plugin Name (for logs)",
         "type": "string",
-        "default": "SLWFOnePro",
-        "required": false
+        "default": "SLWFOnePro"
       },
       "debug": {
         "title": "Enable Debug Logs",
-        "description": "Surface ESPHome state-change chatter to the main log (otherwise sent to log.debug).",
+        "description": "Surface device state-change chatter to the main log (otherwise sent to log.debug).",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": 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.",
+        "title": "Auto-discover SLWF-01Pro devices via mDNS",
+        "description": "Browses the local network for ESPHome `_esphomelib._tcp` services and adds any device that exposes a Climate entity. Only works for unencrypted devices. Manually configured devices in the list below take precedence and are required for any device with the ESPHome API encryption key set.",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "discoveryTimeout": {
         "title": "Discovery timeout (seconds)",
@@ -33,122 +30,107 @@
         "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
+        "default": false
       },
       "disableOutdoorTempSensor": {
         "title": "Hide Outdoor Temperature sensor service",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "disablePowerSensor": {
         "title": "Hide Power Usage characteristic (Eve.Energy)",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "disableBeeperSwitch": {
         "title": "Hide Beeper switch",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "disableDisplaySwitch": {
         "title": "Hide Display Toggle switch",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "disableDryMode": {
         "title": "Hide DRY mode switch",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "disableFanOnlyMode": {
         "title": "Hide FAN_ONLY mode switch",
         "type": "boolean",
-        "default": false,
-        "required": false
+        "default": false
       },
       "devices": {
         "type": "array",
-        "required": false,
         "items": {
-          "title": "Devices",
+          "title": "Device",
           "type": "object",
+          "required": ["name", "host"],
           "properties": {
             "name": {
               "title": "Display name in HomeKit",
               "type": "string",
-              "required": true
+              "minLength": 1
             },
             "host": {
               "title": "Hostname or IP address",
               "type": "string",
-              "required": true
+              "minLength": 1
             },
             "port": {
-              "title": "ESPHome native API port",
+              "title": "Native API port",
+              "description": "ESPHome's native API port. Default 6053; rarely needs changing.",
               "type": "integer",
               "default": 6053,
               "minimum": 1,
-              "maximum": 65535,
-              "required": false
+              "maximum": 65535
             },
             "encryptionKey": {
-              "title": "ESPHome API Noise encryption key (base64)",
-              "type": "string",
-              "required": false
+              "title": "API encryption key (base64)",
+              "description": "If your device's ESPHome YAML has `api.encryption.key:` set, paste the same base64 key here. Leave empty if encryption isn't enabled.",
+              "type": "string"
             },
             "disableHumiditySensor": {
               "title": "Hide Humidity sensor for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             },
             "disableOutdoorTempSensor": {
               "title": "Hide Outdoor Temperature for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             },
             "disablePowerSensor": {
               "title": "Hide Power Usage for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             },
             "disableBeeperSwitch": {
               "title": "Hide Beeper switch for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             },
             "disableDisplaySwitch": {
               "title": "Hide Display Toggle for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             },
             "disableDryMode": {
               "title": "Hide DRY mode switch for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             },
             "disableFanOnlyMode": {
               "title": "Hide FAN_ONLY mode switch for this device",
               "type": "boolean",
-              "default": false,
-              "required": false
+              "default": false
             }
           }
         }
@@ -184,7 +166,7 @@
       "key": "devices",
       "type": "array",
       "title": "Manual device list",
-      "description": "Optional. Required for encrypted ESPHome devices. Per-device toggles override the globals.",
+      "description": "Optional. Required for any device with the ESPHome API encryption key set (mDNS doesn't broadcast it, so auto-discovery alone won't work for those). Per-device toggles override the globals.",
       "orderable": false,
       "buttonText": "Add Device",
       "expandable": true,

package/index.js

@@ -1,10 +1,10 @@
-const ESPHome = require('./lib/esphome');
+const Esphome = require('./lib/esphome');
 
 const PLUGIN_NAME = 'homebridge-slwf-01pro';
 const PLATFORM_NAME = 'SLWFOnePro';
 const ACCESSORY_SCHEMA_VERSION = 2;
 
-class ESPHomeAC {
+class SLWFOnePro {
 	constructor(log, config, api) {
 		this.api = api;
 		this.log = log;
@@ -36,7 +36,7 @@ class ESPHomeAC {
 		};
 
 		this.api.on('didFinishLaunching', () => {
-			Promise.resolve(ESPHome.init.call(this)).catch(err => {
+			Promise.resolve(Esphome.init.call(this)).catch(err => {
 				this.log.error(`Plugin initialization failed: ${err.message || err}`);
 			});
 		});
@@ -55,5 +55,5 @@ class ESPHomeAC {
 }
 
 module.exports = (api) => {
-	api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, ESPHomeAC, true);
+	api.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, SLWFOnePro, true);
 };

package/lib/DeviceAccessory.js

@@ -93,8 +93,8 @@ class DeviceAccessory {
 		}
 		this.host = device.host;
 		this.serial = this.deviceInfo.macAddress || this.id;
-		this.manufacturer = this.deviceInfo.manufacturer || 'ESPHome';
-		this.model = this.deviceInfo.model || climate.name || 'ESPHome AC';
+		this.manufacturer = this.deviceInfo.manufacturer || 'SMLIGHT';
+		this.model = this.deviceInfo.model || climate.name || 'SLWF-01Pro';
 		this.firmwareRevision = sanitizeFirmwareRevision(this.deviceInfo.esphomeVersion);
 
 		this.state = climate.state || {};
@@ -109,7 +109,7 @@ class DeviceAccessory {
 		this.accessory = platform.accessories.find(acc => acc.UUID === this.UUID);
 
 		if (!this.accessory) {
-			this.log(`Creating new ESPHome AC accessory: "${this.name}"`);
+			this.log(`Creating new SLWF-01Pro accessory: "${this.name}"`);
 			this.accessory = new this.api.platformAccessory(this.name, this.UUID);
 			this.accessory.context.schemaVersion = ACCESSORY_SCHEMA_VERSION;
 			this.accessory.context.deviceId = this.id;
@@ -118,7 +118,7 @@ class DeviceAccessory {
 			platform.accessories.push(this.accessory);
 			this.api.registerPlatformAccessories(platform.PLUGIN_NAME, platform.PLATFORM_NAME, [this.accessory]);
 		} else {
-			this.log(`ESPHome device "${this.name}" reconnected.`);
+			this.log(`Device "${this.name}" reconnected.`);
 			this.accessory.context.schemaVersion = ACCESSORY_SCHEMA_VERSION;
 			this.accessory.context.host = this.host;
 			if (PRIMARY_MODES.includes(this.state.mode)) {

package/lib/esphome.js

@@ -112,7 +112,7 @@ async function init() {
 
 	if (allDevices.length === 0) {
 		if (manualDevices.length === 0 && (!platform.autoDiscover || discoverySucceeded)) {
-			platform.log('No ESPHome devices configured and none discovered. Plugin will idle.');
+			platform.log('No SLWF-01Pro / ESPHome devices configured and none discovered. Plugin will idle.');
 			pruneOrphanedAccessories(platform, []);
 		} else {
 			platform.log.error('Auto-discovery returned no devices and no manual devices configured — keeping cached accessories. Will retry on next restart.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-slwf-01pro",
-  "description": "Homebridge plugin for the SMLIGHT SLWF-01Pro Wi-Fi dongle and other ESPHome Climate entities. Auto-discovery, multi-entity bundling, and full Midea-protocol AC support.",
-  "version": "0.3.2",
+  "description": "Homebridge plugin for the SMLIGHT SLWF-01Pro Wi-Fi AC dongle. Auto-discovery, multi-entity bundling, and full Midea-protocol support over the ESPHome native API.",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nookied/homebridge-SLWF-01Pro.git"
@@ -9,20 +9,19 @@
   "homepage": "https://github.com/nookied/homebridge-SLWF-01Pro#readme",
   "license": "MIT",
   "preferGlobal": true,
-  "displayName": "Homebridge SLWF-01Pro / ESPHome AC",
+  "displayName": "Homebridge SLWF-01Pro",
   "keywords": [
     "homebridge-plugin",
-    "homebridge-esphome",
-    "homebridge-esphome-ac",
-    "esphome",
-    "esphome-ac",
-    "climate",
     "slwf",
     "slwf-01pro",
+    "smlight",
     "midea",
     "electrolux",
     "beko",
-    "neoclima"
+    "neoclima",
+    "air-conditioner",
+    "climate",
+    "esphome"
   ],
   "bugs": {
     "url": "https://github.com/nookied/homebridge-SLWF-01Pro/issues"
@@ -45,6 +44,8 @@
     "fakegato-history": "^0.6.7"
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "eslint": "^8.46.0",
     "jest": "^29.7.0"
   },