homebridge-mrcool-hvac 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format is inspired by Keep a Changelog and Semantic Versioning.
+
+## [0.1.0] - 2025-09-14
+### Added
+- Initial public preview.
+- SSE event subscription with automatic reconnect.
+- Thermostat service (OFF / HEAT / COOL / AUTO) with 0.5°C step.
+- Outdoor temperature sensor.
+- Humidity reporting (if provided by device climate state).
+- Beeper on/off switch + optional autoDisableBeeper.
+- Differential debounced command sender & acknowledgement timeout warnings.
+- Detailed debug logging (raw climate payload + mapped state, state id enumeration, missing climate warning).
+- Optional experimental preset & swing switches (device currently ignores commands).
+
+### Removed
+- Display Toggle and Swing Step button services (no observable device effect).
+
+### Notes
+- Preset & swing retained as optional for future firmware support.
+- Future roadmap: fan speed granularity, multi-unit discovery, config schema publication.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 YOUR NAME
+
+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,162 @@
+## homebridge-mrcool-smartlight
+
+Homebridge plugin providing local (cloud‑independent) control of a MrCool HVAC unit through the SMARTLIGHT SLWF‑01 Pro Wi‑Fi module using its Server‑Sent Events (SSE) event stream and simple HTTP command endpoints.
+
+> Status: Early preview. Core thermostat + outdoor temperature + beeper work reliably. Preset / swing features are exposed optionally but the device currently ignores those commands. Removed non‑functional Display / Swing Step buttons to keep the UI clean.
+
+### Working Today
+* Thermostat: OFF / HEAT / COOL / AUTO (HEAT_COOL) + current temperature, target temperature, and AUTO heating/cooling thresholds (16–30°C, 0.5° steps)
+* Current relative humidity (if provided by climate entity)
+* Outdoor temperature sensor (separate TemperatureSensor)
+* Beeper on/off switch (stateful)
+* Differential, debounced command sending with acknowledgement timeout
+* Robust SSE subscription with automatic reconnect + missing‑climate warning
+* Detailed debug logging (raw climate payload, mapped state, every SSE state id)
+
+### Optional / Experimental
+* Preset switches (BOOST / ECO / SLEEP) – device accepts HTTP 200 but no observable effect
+* Swing mode switch (BOTH / OFF) – currently not reflected by SSE (likely ignored)
+* Fan Only & Dry “modes” (implemented as helper switches mapping to internal state logic)
+
+### Removed (No observable effect)
+* Display Toggle button
+* Swing Step button
+
+---
+
+## Installation
+
+### Via Homebridge UI (recommended)
+When published to npm (e.g. `homebridge-mrcool-smartlight`):
+1. Open Homebridge UI -> Plugins.
+2. Search for `mrcool smartlight`.
+3. Install and configure.
+
+### Manual / Local (development)
+```bash
+git clone https://github.com/your-user/homebridge-mrcool-smartlight.git
+cd homebridge-mrcool-smartlight
+npm install
+npm run build
+npm link      # optional: makes it available globally
+homebridge -D # start Homebridge and test
+```
+
+Or inside your existing mapped custom-plugins folder (Docker):
+```bash
+docker exec -it homebridge bash
+cd /homebridge/custom-plugins/homebridge-mrcool-smartlight
+npm install
+npm run build
+```
+
+---
+## Configuration (config.json)
+
+Minimal:
+```json
+{
+  "accessory": "MrCoolSmartLight",
+  "name": "MrCool HVAC",
+  "ip": "192.168.40.149",
+  "mac": "f8:b3:b7:8a:d6:b8"
+}
+```
+
+Extended (with options):
+```json
+{
+  "accessory": "MrCoolSmartLight",
+  "name": "MrCool HVAC",
+  "ip": "192.168.40.149",
+  "mac": "f8:b3:b7:8a:d6:b8",
+  "climateEntityId": "climate-air_conditioner",
+  "commandDebounceMs": 450,
+  "ackTimeoutMs": 5000,
+  "autoDisableBeeper": true,
+  "enablePresets": false,
+  "enableSwing": false,
+  "enableFanOnly": false,
+  "enableDryMode": false,
+  "debug": true
+}
+```
+
+### Option Reference
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `ip` | string | (required) | IPv4/host of the SMARTLIGHT module. |
+| `mac` | string | (recommended) | MAC used for stable UUID (prevents accessory duplication). |
+| `climateEntityId` | string | auto-discovered | Explicit climate entity id (e.g. `climate-air_conditioner`) if SSE discovery is delayed/missing. |
+| `commandDebounceMs` | number | 450 | Merge rapid HomeKit changes before sending to device. |
+| `ackTimeoutMs` | number | 5000 | Warn if SSE doesn’t reflect sent change within this window. |
+| `autoDisableBeeper` | boolean | false | Automatically turns beeper off after connecting. |
+| `enablePresets` | boolean | false | Expose preset switches (experimental; device ignores). |
+| `enableSwing` | boolean | false | Expose swing BOTH/OFF switch (experimental; ignored). |
+| `enableFanOnly` | boolean | false | Expose Fan Only helper switch (maps to target state logic). |
+| `enableDryMode` | boolean | false | Expose Dry helper switch. |
+| `debug` | boolean | false | Verbose internal & raw SSE logging. |
+
+---
+## How It Works
+* Subscribes to `/events` SSE endpoint; parses climate, sensor, and switch state ids.
+* Maintains internal cached state; reconciles HomeKit commands vs. device reports.
+* AUTO mode uses HomeKit heating/cooling threshold temperatures as a synthetic range and switches the device between HEAT/COOL/OFF as the room temperature crosses those bounds.
+* Sends updates via `POST /climate/<id>/set?mode=...&target_temperature=...` (only when changed).
+* Beeper switch maps to `/switch/air_conditioner_beeper/(turn_on|turn_off)`.
+* Optional commands for presets/swing are issued but currently produce no state change.
+
+If the module firmware begins honoring ignored parameters, the exposed optional switches will immediately become useful without code changes.
+
+---
+## Known Limitations
+* No fan speed granularity (only implicit via thermostat modes).
+* Preset & swing currently inert (device returns HTTP 200 without state mutation).
+* AUTO is synthetic: the device still receives ordinary HEAT/COOL/OFF commands plus the matching setpoint for the active side of the range.
+* No caching across restarts beyond what HomeKit retains.
+* Single-unit support per accessory instance (add multiple accessories for multiple units).
+
+---
+## Troubleshooting
+| Symptom | Suggestion |
+|---------|------------|
+| Thermostat stuck / no updates | Enable `debug`, restart, confirm climate SSE events appear. |
+| Values don’t apply from HomeKit | Set `climateEntityId` explicitly (usually `climate-air_conditioner`) so writes don’t wait on SSE discovery. |
+| Commands delayed | Lower `commandDebounceMs` (e.g. 200) but keep >150ms to avoid floods. |
+| Ack timeout warnings | Verify device actually changed; network latency; increase `ackTimeoutMs`. |
+| Duplicate accessories | Ensure `mac` is set and stable. Remove cached accessory from Homebridge UI. |
+
+---
+## Development
+Scripts:
+```bash
+npm run build   # compile TypeScript
+npm run watch   # incremental build
+npm pack        # preview package tarball
+```
+
+The build emits JavaScript + declarations into `dist/` (only contents published). Use `npm run pack:check` to review included files before publishing.
+
+---
+## Publishing (Maintainers)
+1. Update version in `package.json` (semver).
+2. Update `CHANGELOG.md`.
+3. `npm run build` & `npm run pack:check`.
+4. `npm publish` (ensure you are logged in and have 2FA if required).
+5. Create a Git tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+
+---
+## Security
+This plugin performs only local HTTP(S) calls to the configured IP. No data leaves your network unless your Homebridge instance uploads logs elsewhere.
+
+---
+## License
+MIT — see `LICENSE` file.
+
+---
+## Changelog (Excerpt)
+See full details in `CHANGELOG.md`.
+
+### 0.1.0
+* Initial public preview: core thermostat, outdoor temperature, beeper, SSE integration, optional experimental switches.
+

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { API } from 'homebridge';
+declare const _default: (api: API) => void;
+export default _default;

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mrcoolAccessory_1 = require("./mrcoolAccessory");
+const ACCESSORY_NAME = 'MrCoolSmartLight';
+exports.default = (api) => {
+    api.registerAccessory(ACCESSORY_NAME, mrcoolAccessory_1.MrCoolSmartLightAccessory);
+};

package/dist/mrcoolAccessory.d.ts

@@ -0,0 +1,93 @@
+import { API, AccessoryConfig, AccessoryPlugin, Logging, Service } from 'homebridge';
+interface MrCoolConfig extends AccessoryConfig {
+    ip?: string;
+    mac?: string;
+    climateEntityId?: string;
+    name: string;
+    pollInterval?: number;
+    enableFanOnly?: boolean;
+    enableDryMode?: boolean;
+    enablePresets?: boolean;
+    enableSwing?: boolean;
+    autoDisableBeeper?: boolean;
+    commandDebounceMs?: number;
+    ackTimeoutMs?: number;
+    mock?: boolean;
+    debug?: boolean;
+}
+export declare class MrCoolSmartLightAccessory implements AccessoryPlugin {
+    private readonly log;
+    private readonly config;
+    private readonly hap;
+    private readonly api;
+    private thermostatService;
+    private informationService;
+    private humidityService?;
+    private outdoorTempService?;
+    private fanOnlySwitch?;
+    private dryModeSwitch?;
+    private presetSwitches;
+    private swingSwitch?;
+    private beeperSwitch?;
+    private currentTemp;
+    private targetTemp;
+    private heatingThresholdTemp;
+    private coolingThresholdTemp;
+    private outdoorTemp;
+    private beeperOn;
+    private currentState;
+    private targetState;
+    private humidity;
+    private internalMode;
+    private pollTimer?;
+    private es?;
+    private climateEntityId;
+    private pendingReconnectDelay;
+    private pendingSendTimer?;
+    private lastSentMode?;
+    private lastSentTarget?;
+    private debounceMs;
+    private ackTimeoutMs;
+    private pendingAck?;
+    private currentPreset;
+    private currentSwingMode;
+    private normalizeClimateEntityId;
+    constructor(log: Logging, config: MrCoolConfig, api: API);
+    private debug;
+    private setInternalMode;
+    private applyInternalModeToCurrent;
+    private scheduleSyncToDevice;
+    private buildDeviceMode;
+    private roundTemp;
+    private clampTemp;
+    private normalizeAutoThresholds;
+    private syncTargetTempFromAutoRange;
+    private setAutoRangeFromTarget;
+    private getEffectiveMode;
+    private getEffectiveTargetTemp;
+    private flushPendingSend;
+    private pollStatus;
+    private updateCharacteristics;
+    private handleCurrentStateGet;
+    private handleTargetStateGet;
+    private handleTargetStateSet;
+    private handleCurrentTempGet;
+    private handleTargetTempGet;
+    private handleTargetTempSet;
+    private handleHeatingThresholdTempGet;
+    private handleCoolingThresholdTempGet;
+    private handleHeatingThresholdTempSet;
+    private handleCoolingThresholdTempSet;
+    getServices(): Service[];
+    private connectEventStream;
+    private scheduleReconnect;
+    private cleanupEventStream;
+    private handleClimateState;
+    private requestPreset;
+    private requestSwing;
+    private disableBeeper;
+    private startAck;
+    private checkAckSatisfied;
+    private sendBeeper;
+}
+export {};

package/dist/mrcoolAccessory.js

@@ -0,0 +1,748 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MrCoolSmartLightAccessory = void 0;
+const axios_1 = __importDefault(require("axios"));
+const eventsource_1 = __importDefault(require("eventsource"));
+class MrCoolSmartLightAccessory {
+    normalizeClimateEntityId(id) {
+        return id.startsWith('climate-') ? id : `climate-${id}`;
+    }
+    constructor(log, config, api) {
+        this.presetSwitches = {};
+        this.currentTemp = 22;
+        this.targetTemp = 22;
+        this.heatingThresholdTemp = 21;
+        this.coolingThresholdTemp = 23;
+        this.outdoorTemp = NaN;
+        this.beeperOn = false;
+        this.humidity = 45;
+        this.internalMode = 'off';
+        this.climateEntityId = null; // e.g. climate-air_conditioner
+        this.pendingReconnectDelay = 5000;
+        this.debounceMs = 450; // settle window for batching mode+temp
+        this.ackTimeoutMs = 5000;
+        this.currentPreset = 'NONE';
+        this.currentSwingMode = 'OFF';
+        this.log = log;
+        this.config = config;
+        this.api = api;
+        this.hap = api.hap;
+        if (!config.ip && !config.mock) {
+            throw new Error('MrCoolSmartLight: ip is required unless mock=true');
+        }
+        if (typeof config.climateEntityId === 'string' && config.climateEntityId.trim().length > 0) {
+            this.climateEntityId = this.normalizeClimateEntityId(config.climateEntityId.trim());
+        }
+        this.currentState = this.hap.Characteristic.CurrentHeatingCoolingState.OFF;
+        this.targetState = this.hap.Characteristic.TargetHeatingCoolingState.OFF;
+        // Thermostat service
+        this.thermostatService = new this.hap.Service.Thermostat(config.name);
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.CurrentHeatingCoolingState)
+            .on('get', this.handleCurrentStateGet.bind(this));
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.TargetHeatingCoolingState)
+            .on('get', this.handleTargetStateGet.bind(this))
+            .on('set', this.handleTargetStateSet.bind(this));
+        // Ensure AUTO is explicitly exposed (some Home apps hide it if props constrained elsewhere)
+        const tState = this.hap.Characteristic.TargetHeatingCoolingState;
+        this.thermostatService.getCharacteristic(tState).setProps({
+            validValues: [tState.OFF, tState.HEAT, tState.COOL, tState.AUTO],
+        });
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.CurrentTemperature)
+            .on('get', this.handleCurrentTempGet.bind(this));
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.TargetTemperature)
+            .on('get', this.handleTargetTempGet.bind(this))
+            .on('set', this.handleTargetTempSet.bind(this));
+        // Device only accepts 0.5C steps and (from testing) roughly 16-30C range (reports 29.0 when set to 30 sometimes)
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.TargetTemperature).setProps({
+            minValue: 16,
+            maxValue: 30,
+            minStep: 0.5,
+        });
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.HeatingThresholdTemperature)
+            .on('get', this.handleHeatingThresholdTempGet.bind(this))
+            .on('set', this.handleHeatingThresholdTempSet.bind(this));
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.CoolingThresholdTemperature)
+            .on('get', this.handleCoolingThresholdTempGet.bind(this))
+            .on('set', this.handleCoolingThresholdTempSet.bind(this));
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.HeatingThresholdTemperature).setProps({
+            minValue: 16,
+            maxValue: 30,
+            minStep: 0.5,
+        });
+        this.thermostatService.getCharacteristic(this.hap.Characteristic.CoolingThresholdTemperature).setProps({
+            minValue: 16,
+            maxValue: 30,
+            minStep: 0.5,
+        });
+        // Humidity (placeholder)
+        this.humidityService = new this.hap.Service.HumiditySensor(config.name + ' Humidity');
+        this.humidityService.getCharacteristic(this.hap.Characteristic.CurrentRelativeHumidity)
+            .on('get', (cb) => cb(null, this.humidity));
+        // Outdoor temperature (TemperatureSensor). Created eagerly; updated when SSE provides value.
+        this.outdoorTempService = new this.hap.Service.TemperatureSensor(config.name + ' Outdoor Temperature', 'outdoorTemp');
+        this.outdoorTempService.getCharacteristic(this.hap.Characteristic.CurrentTemperature)
+            .on('get', (cb) => cb(null, isNaN(this.outdoorTemp) ? 0 : this.outdoorTemp));
+        // Beeper switch (stateful)
+        this.beeperSwitch = new this.hap.Service.Switch(config.name + ' Beeper', 'beeper');
+        this.beeperSwitch.getCharacteristic(this.hap.Characteristic.On)
+            .on('get', (cb) => cb(null, this.beeperOn))
+            .on('set', (value, cb) => {
+            const on = !!value;
+            this.sendBeeper(on).catch(err => this.debug('beeper set error', err));
+            this.beeperOn = on; // optimistic
+            if (this.beeperSwitch)
+                this.beeperSwitch.updateCharacteristic(this.hap.Characteristic.On, this.beeperOn);
+            cb(null);
+        });
+        // Fan-only switch
+        if (config.enableFanOnly) {
+            this.fanOnlySwitch = new this.hap.Service.Switch(config.name + ' Fan Only', 'fanOnly');
+            this.fanOnlySwitch.getCharacteristic(this.hap.Characteristic.On)
+                .on('get', (cb) => cb(null, this.internalMode === 'fan'))
+                .on('set', (value, cb) => {
+                const on = !!value;
+                if (on) {
+                    this.setInternalMode('fan');
+                }
+                else if (this.internalMode === 'fan') {
+                    this.setInternalMode('off');
+                }
+                cb(null);
+            });
+        }
+        // Dry mode switch
+        if (config.enableDryMode) {
+            this.dryModeSwitch = new this.hap.Service.Switch(config.name + ' Dry Mode', 'dryMode');
+            this.dryModeSwitch.getCharacteristic(this.hap.Characteristic.On)
+                .on('get', (cb) => cb(null, this.internalMode === 'dry'))
+                .on('set', (value, cb) => {
+                const on = !!value;
+                if (on) {
+                    this.setInternalMode('dry');
+                }
+                else if (this.internalMode === 'dry') {
+                    this.setInternalMode('off');
+                }
+                cb(null);
+            });
+        }
+        // Optional preset switches (BOOST / ECO / SLEEP) – experimental: device appears to ignore preset changes in testing.
+        if (config.enablePresets) {
+            ['BOOST', 'ECO', 'SLEEP'].forEach(preset => {
+                const svc = new this.hap.Service.Switch(`${config.name} ${preset} Preset`, `preset-${preset}`);
+                svc.getCharacteristic(this.hap.Characteristic.On)
+                    .on('get', (cb) => cb(null, this.currentPreset === preset))
+                    .on('set', (value, cb) => {
+                    const on = !!value;
+                    // Only one preset active; turning one on turns others off; turning off reverts to NONE
+                    if (on) {
+                        this.requestPreset(preset);
+                    }
+                    else if (this.currentPreset === preset) {
+                        this.requestPreset('NONE');
+                    }
+                    cb(null);
+                });
+                this.presetSwitches[preset] = svc;
+            });
+        }
+        // Optional swing switch toggles BOTH vs OFF (experimental; device ignored in testing)
+        if (config.enableSwing) {
+            this.swingSwitch = new this.hap.Service.Switch(`${config.name} Swing`, 'swing');
+            this.swingSwitch.getCharacteristic(this.hap.Characteristic.On)
+                .on('get', (cb) => cb(null, this.currentSwingMode === 'BOTH'))
+                .on('set', (value, cb) => {
+                const on = !!value;
+                this.requestSwing(on ? 'BOTH' : 'OFF');
+                cb(null);
+            });
+        }
+        // Accessory info
+        this.informationService = new this.hap.Service.AccessoryInformation()
+            .setCharacteristic(this.hap.Characteristic.Manufacturer, 'MrCool')
+            .setCharacteristic(this.hap.Characteristic.Model, 'SmartLight SLWF-01 Pro')
+            .setCharacteristic(this.hap.Characteristic.SerialNumber, config.mac || 'Unknown');
+        // Configurable debounce / ack timeouts
+        if (typeof config.commandDebounceMs === 'number' && config.commandDebounceMs >= 100 && config.commandDebounceMs <= 5000) {
+            this.debounceMs = config.commandDebounceMs;
+        }
+        if (typeof config.ackTimeoutMs === 'number' && config.ackTimeoutMs >= 500 && config.ackTimeoutMs <= 15000) {
+            this.ackTimeoutMs = config.ackTimeoutMs;
+        }
+        if (this.config.mock) {
+            const interval = (config.pollInterval || 30) * 1000;
+            this.pollTimer = setInterval(() => this.pollStatus().catch(err => this.debug('Poll error', err)), interval);
+            setTimeout(() => this.pollStatus().catch(() => undefined), 1000);
+        }
+        else {
+            this.connectEventStream();
+        }
+    }
+    // Debug logging disabled (stripped for production minimal logs)
+    debug(..._msg) { }
+    setInternalMode(mode) {
+        this.internalMode = mode;
+        this.debug('Set internal mode:', mode);
+        // Sync thermostat target when relevant
+        const t = this.hap.Characteristic.TargetHeatingCoolingState;
+        switch (mode) {
+            case 'cool':
+                this.targetState = t.COOL;
+                break;
+            case 'heat':
+                this.targetState = t.HEAT;
+                break;
+            case 'auto':
+                this.targetState = t.AUTO;
+                this.syncTargetTempFromAutoRange();
+                break;
+            case 'off':
+            case 'fan':
+            case 'dry':
+                this.targetState = t.OFF;
+                break; // fan & dry not native -> OFF target
+        }
+        this.applyInternalModeToCurrent();
+        this.scheduleSyncToDevice();
+        this.updateCharacteristics();
+    }
+    applyInternalModeToCurrent() {
+        const c = this.hap.Characteristic.CurrentHeatingCoolingState;
+        switch (this.getEffectiveMode()) {
+            case 'cool':
+                this.currentState = c.COOL;
+                break;
+            case 'heat':
+                this.currentState = c.HEAT;
+                break;
+            case 'fan':
+            case 'dry':
+            case 'off':
+            default:
+                this.currentState = c.OFF;
+                break;
+        }
+    }
+    // Schedule a debounced differential sync to device using query parameters only
+    scheduleSyncToDevice() {
+        if (this.config.mock)
+            return; // no outbound when mocking
+        if (this.pendingSendTimer)
+            clearTimeout(this.pendingSendTimer);
+        this.pendingSendTimer = setTimeout(() => this.flushPendingSend().catch(err => this.debug('flushPendingSend error', err)), this.debounceMs);
+    }
+    buildDeviceMode() {
+        const deviceModeMap = {
+            off: 'OFF',
+            cool: 'COOL',
+            heat: 'HEAT',
+            auto: 'HEAT_COOL',
+            fan: 'FAN_ONLY',
+            dry: 'DRY',
+        };
+        return deviceModeMap[this.getEffectiveMode()];
+    }
+    roundTemp(v) {
+        const stepped = Math.round(v * 2) / 2;
+        return stepped;
+    }
+    clampTemp(v) {
+        return Math.min(30, Math.max(16, this.roundTemp(v)));
+    }
+    normalizeAutoThresholds(changed = 'none') {
+        this.heatingThresholdTemp = this.clampTemp(this.heatingThresholdTemp);
+        this.coolingThresholdTemp = this.clampTemp(this.coolingThresholdTemp);
+        if (this.coolingThresholdTemp - this.heatingThresholdTemp < 0.5) {
+            if (changed === 'heat') {
+                this.coolingThresholdTemp = this.clampTemp(this.heatingThresholdTemp + 0.5);
+                if (this.coolingThresholdTemp - this.heatingThresholdTemp < 0.5) {
+                    this.heatingThresholdTemp = this.clampTemp(this.coolingThresholdTemp - 0.5);
+                }
+            }
+            else if (changed === 'cool') {
+                this.heatingThresholdTemp = this.clampTemp(this.coolingThresholdTemp - 0.5);
+                if (this.coolingThresholdTemp - this.heatingThresholdTemp < 0.5) {
+                    this.coolingThresholdTemp = this.clampTemp(this.heatingThresholdTemp + 0.5);
+                }
+            }
+            else {
+                const midpoint = this.roundTemp((this.heatingThresholdTemp + this.coolingThresholdTemp) / 2);
+                this.heatingThresholdTemp = this.clampTemp(midpoint - 0.5);
+                this.coolingThresholdTemp = this.clampTemp(midpoint + 0.5);
+            }
+        }
+    }
+    syncTargetTempFromAutoRange() {
+        this.targetTemp = this.roundTemp((this.heatingThresholdTemp + this.coolingThresholdTemp) / 2);
+    }
+    setAutoRangeFromTarget(center) {
+        const currentSpan = Math.max(0.5, this.coolingThresholdTemp - this.heatingThresholdTemp);
+        const halfSpan = Math.max(0.25, currentSpan / 2);
+        this.heatingThresholdTemp = this.clampTemp(center - halfSpan);
+        this.coolingThresholdTemp = this.clampTemp(center + halfSpan);
+        this.normalizeAutoThresholds();
+        this.syncTargetTempFromAutoRange();
+    }
+    getEffectiveMode() {
+        if (this.internalMode !== 'auto')
+            return this.internalMode;
+        this.normalizeAutoThresholds();
+        if (this.currentTemp <= this.heatingThresholdTemp)
+            return 'heat';
+        if (this.currentTemp >= this.coolingThresholdTemp)
+            return 'cool';
+        return 'off';
+    }
+    getEffectiveTargetTemp() {
+        if (this.internalMode !== 'auto') {
+            return this.roundTemp(this.targetTemp);
+        }
+        const effectiveMode = this.getEffectiveMode();
+        if (effectiveMode === 'heat')
+            return this.heatingThresholdTemp;
+        if (effectiveMode === 'cool')
+            return this.coolingThresholdTemp;
+        return this.lastSentTarget === undefined ? this.targetTemp : this.lastSentTarget;
+    }
+    async flushPendingSend() {
+        if (this.config.mock)
+            return;
+        const ip = this.config.ip;
+        if (!ip)
+            return;
+        if (!this.climateEntityId) {
+            this.debug('Deferring send; climate entity not yet discovered');
+            // retry shortly until SSE gives us the entity id
+            this.pendingSendTimer = setTimeout(() => this.flushPendingSend().catch(() => undefined), 1500);
+            return;
+        }
+        const deviceMode = this.buildDeviceMode();
+        const desiredTarget = this.getEffectiveTargetTemp();
+        const params = [];
+        if (deviceMode !== this.lastSentMode)
+            params.push(`mode=${encodeURIComponent(deviceMode)}`);
+        if (this.lastSentTarget === undefined || Math.abs(desiredTarget - this.lastSentTarget) > 0.001) {
+            params.push(`target_temperature=${desiredTarget.toFixed(1)}`);
+        }
+        if (params.length === 0) {
+            this.debug('No diff to send (mode/temperature unchanged)');
+            return;
+        }
+        // Device silently ignores fan_mode changes so we skip sending fan_mode entirely for now.
+        const endpoint = `http://${ip}/climate/${this.climateEntityId.replace('climate-', '')}/set?${params.join('&')}`;
+        this.debug('Sending diff to device', endpoint);
+        // sending diff to device (debug removed)
+        // no diff to send
+        // deferring send; climate entity not yet discovered
+        try {
+            this.startAck(params.some(p => p.startsWith('mode=')) ? deviceMode : undefined, params.some(p => p.startsWith('target_temperature=')) ? desiredTarget : undefined);
+            await axios_1.default.post(endpoint, undefined, { timeout: 5000 });
+            // Optimistically update lastSent markers (SSE confirmation will reconcile internalMode/targetTemp anyway)
+            if (params.some(p => p.startsWith('mode=')))
+                this.lastSentMode = deviceMode;
+            if (params.some(p => p.startsWith('target_temperature=')))
+                this.lastSentTarget = desiredTarget;
+        }
+        catch (e) {
+            this.pendingAck = undefined;
+            this.log.warn('Command POST failed', e.message || e);
+        }
+    }
+    async pollStatus() {
+        if (this.config.mock) {
+            // Simulate drift and cyclic modes
+            this.currentTemp += (Math.random() - 0.5) * 0.2;
+            this.applyInternalModeToCurrent();
+            if (this.internalMode === 'auto')
+                this.scheduleSyncToDevice();
+            this.updateCharacteristics();
+            return;
+        }
+        // When not in mock, we rely on SSE; no polling here.
+    }
+    updateCharacteristics() {
+        this.thermostatService.updateCharacteristic(this.hap.Characteristic.CurrentTemperature, this.currentTemp);
+        this.thermostatService.updateCharacteristic(this.hap.Characteristic.TargetTemperature, this.targetTemp);
+        this.thermostatService.updateCharacteristic(this.hap.Characteristic.HeatingThresholdTemperature, this.heatingThresholdTemp);
+        this.thermostatService.updateCharacteristic(this.hap.Characteristic.CoolingThresholdTemperature, this.coolingThresholdTemp);
+        this.thermostatService.updateCharacteristic(this.hap.Characteristic.CurrentHeatingCoolingState, this.currentState);
+        this.thermostatService.updateCharacteristic(this.hap.Characteristic.TargetHeatingCoolingState, this.targetState);
+        if (this.humidityService)
+            this.humidityService.updateCharacteristic(this.hap.Characteristic.CurrentRelativeHumidity, this.humidity);
+        if (this.fanOnlySwitch)
+            this.fanOnlySwitch.updateCharacteristic(this.hap.Characteristic.On, this.internalMode === 'fan');
+        if (this.dryModeSwitch)
+            this.dryModeSwitch.updateCharacteristic(this.hap.Characteristic.On, this.internalMode === 'dry');
+        Object.entries(this.presetSwitches).forEach(([preset, svc]) => {
+            svc.updateCharacteristic(this.hap.Characteristic.On, this.currentPreset === preset);
+        });
+        if (this.swingSwitch)
+            this.swingSwitch.updateCharacteristic(this.hap.Characteristic.On, this.currentSwingMode === 'BOTH');
+    }
+    // Handlers
+    handleCurrentStateGet(callback) { callback(null, this.currentState); }
+    handleTargetStateGet(callback) { callback(null, this.targetState); }
+    handleTargetStateSet(value, callback) {
+        const t = this.hap.Characteristic.TargetHeatingCoolingState;
+        if (value === t.COOL)
+            this.setInternalMode('cool');
+        else if (value === t.HEAT)
+            this.setInternalMode('heat');
+        else if (value === t.AUTO)
+            this.setInternalMode('auto');
+        else
+            this.setInternalMode('off');
+        callback(null);
+    }
+    handleCurrentTempGet(callback) { callback(null, this.currentTemp); }
+    handleTargetTempGet(callback) { callback(null, this.targetTemp); }
+    handleTargetTempSet(value, callback) {
+        const nextTarget = value;
+        if (this.internalMode === 'auto') {
+            this.setAutoRangeFromTarget(nextTarget);
+        }
+        else {
+            this.targetTemp = nextTarget;
+        }
+        this.applyInternalModeToCurrent();
+        this.scheduleSyncToDevice();
+        this.updateCharacteristics();
+        callback(null);
+    }
+    handleHeatingThresholdTempGet(callback) { callback(null, this.heatingThresholdTemp); }
+    handleCoolingThresholdTempGet(callback) { callback(null, this.coolingThresholdTemp); }
+    handleHeatingThresholdTempSet(value, callback) {
+        this.heatingThresholdTemp = this.clampTemp(value);
+        this.normalizeAutoThresholds('heat');
+        this.syncTargetTempFromAutoRange();
+        this.applyInternalModeToCurrent();
+        this.scheduleSyncToDevice();
+        this.updateCharacteristics();
+        callback(null);
+    }
+    handleCoolingThresholdTempSet(value, callback) {
+        this.coolingThresholdTemp = this.clampTemp(value);
+        this.normalizeAutoThresholds('cool');
+        this.syncTargetTempFromAutoRange();
+        this.applyInternalModeToCurrent();
+        this.scheduleSyncToDevice();
+        this.updateCharacteristics();
+        callback(null);
+    }
+    getServices() {
+        const base = [this.informationService, this.thermostatService];
+        if (this.humidityService)
+            base.push(this.humidityService);
+        if (this.outdoorTempService)
+            base.push(this.outdoorTempService);
+        if (this.fanOnlySwitch)
+            base.push(this.fanOnlySwitch);
+        if (this.dryModeSwitch)
+            base.push(this.dryModeSwitch);
+        Object.values(this.presetSwitches).forEach(s => base.push(s));
+        if (this.swingSwitch)
+            base.push(this.swingSwitch);
+        if (this.beeperSwitch)
+            base.push(this.beeperSwitch);
+        // display toggle & swing step removed
+        return base;
+    }
+    // --- Event Stream Handling ---
+    connectEventStream() {
+        if (!this.config.ip)
+            return;
+        const url = `http://${this.config.ip}/events`;
+        this.debug('Connecting SSE', url);
+        // connecting SSE
+        try {
+            this.es = new eventsource_1.default(url);
+        }
+        catch (e) {
+            this.log.error('Failed to create EventSource', e.message || e);
+            this.scheduleReconnect();
+            return;
+        }
+        // If we don't discover a climate entity within 12s, emit a warning (helps diagnose missing HEAT_COOL reflection)
+        setTimeout(() => {
+            if (!this.climateEntityId) {
+                this.log.warn('No climate state received yet (still waiting for climate-* SSE events). Check device IP / connectivity.');
+            }
+        }, 12000);
+        this.es.onmessage = (evt) => {
+            // Generic messages (without event field) might not appear; we rely on typed handlers below
+            this.debug('SSE message', evt.data?.slice(0, 120));
+        };
+        this.es.addEventListener('ping', (ev) => {
+            // keep-alive; could parse general metadata
+        });
+        this.es.addEventListener('state', (ev) => {
+            try {
+                const data = JSON.parse(ev.data);
+                if (this.config.debug && data && data.id) {
+                    // debug removed: SSE state id
+                }
+                if (!data || !data.id)
+                    return;
+                if (data.id.startsWith('climate-')) {
+                    this.handleClimateState(data);
+                }
+                else if (data.id === 'sensor-air_conditioner_indoor_humidity' && typeof data.value === 'number') {
+                    this.humidity = data.value;
+                    if (this.humidityService)
+                        this.humidityService.updateCharacteristic(this.hap.Characteristic.CurrentRelativeHumidity, this.humidity);
+                }
+                else if (data.id.startsWith('sensor-air_conditioner_outdoor_temperature')) {
+                    const valRaw = data.value;
+                    let val = NaN;
+                    if (typeof valRaw === 'number')
+                        val = valRaw;
+                    else if (typeof valRaw === 'string') {
+                        const parsed = parseFloat(valRaw);
+                        if (!isNaN(parsed))
+                            val = parsed;
+                    }
+                    if (!isNaN(val)) {
+                        this.outdoorTemp = val;
+                        if (this.outdoorTempService)
+                            this.outdoorTempService.updateCharacteristic(this.hap.Characteristic.CurrentTemperature, this.outdoorTemp);
+                        this.debug('Updated outdoor temperature', this.outdoorTemp);
+                        // updated outdoor temperature
+                    }
+                }
+                else if (data.id === 'switch-air_conditioner_beeper' && typeof data.value === 'string') {
+                    const v = data.value.toLowerCase();
+                    const on = v === 'on';
+                    if (this.beeperOn !== on) {
+                        this.beeperOn = on;
+                        this.beeperSwitch?.updateCharacteristic(this.hap.Characteristic.On, this.beeperOn);
+                        this.debug('Beeper state update', this.beeperOn);
+                        // beeper state update
+                    }
+                }
+            }
+            catch (e) {
+                this.debug('Failed to parse state event', e.message || e);
+                // failed to parse state event
+            }
+        });
+        this.es.addEventListener('log', (ev) => {
+            // Could parse internal debug; ignore for now unless debug enabled
+            if (this.config.debug) {
+                // device internal log ignored
+            }
+        });
+        this.es.onerror = (err) => {
+            this.log.warn('SSE error; will reconnect', err ? JSON.stringify(err) : 'unknown');
+            this.cleanupEventStream();
+            this.scheduleReconnect();
+        };
+    }
+    scheduleReconnect() {
+        if (this.config.mock)
+            return;
+        setTimeout(() => this.connectEventStream(), this.pendingReconnectDelay);
+        // Exponential backoff up to 60s
+        this.pendingReconnectDelay = Math.min(this.pendingReconnectDelay * 2, 60000);
+    }
+    cleanupEventStream() {
+        if (this.es) {
+            try {
+                this.es.close();
+            }
+            catch { /* ignore */ }
+            this.es = undefined;
+        }
+    }
+    handleClimateState(data) {
+        // Raw debug before any mapping so we can diagnose mismatches
+        this.debug('SSE climate raw', {
+            /* debug removed: SSE climate raw */
+            id: data.id,
+            mode: data.mode,
+            current_temperature: data.current_temperature,
+            target_temperature: data.target_temperature,
+            preset: data.preset,
+            swing_mode: data.swing_mode,
+        });
+        if (!this.climateEntityId) {
+            this.climateEntityId = this.normalizeClimateEntityId(data.id); // store full id e.g. climate-air_conditioner
+            this.debug('Discovered climate entity', this.climateEntityId);
+            // discovered climate entity
+            // Optionally auto-disable beeper once after discovery
+            if (this.config.autoDisableBeeper) {
+                this.disableBeeper().catch(err => this.debug('autoDisableBeeper failed', err));
+                this.disableBeeper().catch(() => undefined);
+            }
+        }
+        // Extract numbers (some come as strings)
+        const parseNum = (v) => typeof v === 'number' ? v : (typeof v === 'string' ? parseFloat(v) : NaN);
+        const current = parseNum(data.current_temperature);
+        const target = parseNum(data.target_temperature);
+        if (!isNaN(current))
+            this.currentTemp = current;
+        if (!isNaN(target) && this.internalMode !== 'auto')
+            this.targetTemp = target;
+        if (this.internalMode === 'auto')
+            this.syncTargetTempFromAutoRange();
+        if (typeof data.mode === 'string') {
+            const mode = data.mode.toUpperCase();
+            const map = {
+                'OFF': 'off',
+                'COOL': 'cool',
+                'HEAT': 'heat',
+                'HEAT_COOL': 'auto',
+                'FAN_ONLY': 'fan',
+                'DRY': 'dry',
+            };
+            const internal = map[mode];
+            if (internal && this.internalMode !== 'auto')
+                this.internalMode = internal;
+            // Also update targetState to reflect device-reported mode (previously only updated when user initiated change)
+            const t = this.hap.Characteristic.TargetHeatingCoolingState;
+            switch (this.internalMode === 'auto' ? 'auto' : this.internalMode) {
+                case 'cool':
+                    this.targetState = t.COOL;
+                    break;
+                case 'heat':
+                    this.targetState = t.HEAT;
+                    break;
+                case 'auto':
+                    this.targetState = t.AUTO;
+                    break;
+                default:
+                    this.targetState = t.OFF;
+                    break; // fan/dry/off map to OFF target for HomeKit
+            }
+            // If device reports a mode different from what we last sent, allow future diff (do not overwrite lastSentMode here unless matches)
+            if (this.buildDeviceMode() !== this.lastSentMode) {
+                // divergence - keep lastSentMode as is so a subsequent local change will trigger send
+            }
+            else {
+                // matched; nothing to adjust
+            }
+        }
+        if (typeof data.preset === 'string') {
+            this.currentPreset = data.preset.toUpperCase();
+        }
+        if (typeof data.swing_mode === 'string') {
+            this.currentSwingMode = data.swing_mode.toUpperCase();
+        }
+        // Update lastSentTarget only if matches device (ensures we don't suppress future attempted changes if device rejected)
+        if (!isNaN(target) && (this.lastSentTarget === undefined || Math.abs(target - this.lastSentTarget) < 0.001)) {
+            this.lastSentTarget = target; // confirm
+        }
+        this.checkAckSatisfied();
+        this.applyInternalModeToCurrent();
+        if (this.internalMode === 'auto')
+            this.scheduleSyncToDevice();
+        this.updateCharacteristics();
+        this.debug('SSE climate mapped', {
+            /* debug removed: SSE climate mapped */
+            internalMode: this.internalMode,
+            currentTemp: this.currentTemp,
+            targetTemp: this.targetTemp,
+            currentState: this.currentState,
+            targetState: this.targetState,
+            preset: this.currentPreset,
+            swing: this.currentSwingMode,
+        });
+    }
+    // --- Experimental feature helpers ---
+    async requestPreset(preset) {
+        if (this.config.mock) {
+            this.currentPreset = preset;
+            this.updateCharacteristics();
+            return;
+        }
+        if (!this.config.ip || !this.climateEntityId)
+            return;
+        const endpoint = `http://${this.config.ip}/climate/${this.climateEntityId.replace('climate-', '')}/set?preset=${encodeURIComponent(preset)}`;
+        this.debug('Sending preset request', endpoint);
+        // sending preset request (debug removed)
+        try {
+            await axios_1.default.post(endpoint, undefined, { timeout: 4000 });
+        }
+        catch (e) {
+            this.log.warn('Preset request failed', e.message || e);
+        }
+        // We rely on SSE to update; if not changed, switch will revert on next updateCharacteristics call triggered by other events.
+    }
+    async requestSwing(swing) {
+        if (this.config.mock) {
+            this.currentSwingMode = swing;
+            this.updateCharacteristics();
+            return;
+        }
+        if (!this.config.ip || !this.climateEntityId)
+            return;
+        const endpoint = `http://${this.config.ip}/climate/${this.climateEntityId.replace('climate-', '')}/set?swing_mode=${encodeURIComponent(swing)}`;
+        this.debug('Sending swing request', endpoint);
+        // sending swing request (debug removed)
+        try {
+            await axios_1.default.post(endpoint, undefined, { timeout: 4000 });
+        }
+        catch (e) {
+            this.log.warn('Swing request failed', e.message || e);
+        }
+    }
+    async disableBeeper() {
+        if (this.config.mock || !this.config.ip)
+            return;
+        const endpoint = `http://${this.config.ip}/switch/air_conditioner_beeper/turn_off`;
+        this.debug('Auto disabling beeper');
+        // auto disabling beeper
+        try {
+            await axios_1.default.post(endpoint, undefined, { timeout: 3000 });
+        }
+        catch (e) {
+            this.debug('disableBeeper error', e.message || e);
+        }
+        try {
+            await axios_1.default.post(endpoint, undefined, { timeout: 3000 });
+        }
+        catch { /* ignore */ }
+    }
+    startAck(expectedMode, expectedTarget) {
+        this.pendingAck = { sentAt: Date.now(), expectedMode, expectedTarget };
+        setTimeout(() => {
+            if (this.pendingAck && Date.now() - this.pendingAck.sentAt >= this.ackTimeoutMs) {
+                this.log.warn('No SSE acknowledgement within timeout for mode/temperature change');
+                this.pendingAck = undefined;
+            }
+        }, this.ackTimeoutMs + 50);
+    }
+    checkAckSatisfied() {
+        if (!this.pendingAck)
+            return;
+        const expected = this.pendingAck;
+        let satisfied = true;
+        if (expected.expectedMode && expected.expectedMode !== this.buildDeviceMode())
+            satisfied = false;
+        if (typeof expected.expectedTarget === 'number' && Math.abs(this.targetTemp - expected.expectedTarget) > 0.001)
+            satisfied = false;
+        if (satisfied) {
+            this.debug('Ack satisfied for mode/temperature change');
+            // ack satisfied
+            this.pendingAck = undefined;
+        }
+    }
+    // --- Device control for new switch/button services ---
+    async sendBeeper(on) {
+        if (this.config.mock || !this.config.ip)
+            return;
+        const action = on ? 'turn_on' : 'turn_off';
+        const endpoint = `http://${this.config.ip}/switch/air_conditioner_beeper/${action}`;
+        this.debug('Beeper request', endpoint);
+        // beeper request
+        try {
+            await axios_1.default.post(endpoint, undefined, { timeout: 3000 });
+        }
+        catch (err) {
+            this.log.warn('Beeper request failed', err.message || err);
+        }
+    }
+}
+exports.MrCoolSmartLightAccessory = MrCoolSmartLightAccessory;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "homebridge-mrcool-hvac",
+  "version": "0.1.1",
+  "description": "Homebridge plugin for local MrCool HVAC control via SMARTLIGHT SLWF-01 Pro module (SSE + HTTP).",
+  "license": "MIT",
+  "author": "Nilesh <nilesh@cloudgeni.us>",
+  "homepage": "https://github.com/lvnilesh/homebridge-mrcool-smartlight#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lvnilesh/homebridge-mrcool-smartlight.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lvnilesh/homebridge-mrcool-smartlight/issues"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "homekit",
+    "mrcool",
+    "hvac",
+    "thermostat",
+    "air-conditioner",
+    "smartlight",
+    "sse"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "homebridge": ">=1.6.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "watch": "tsc -w -p .",
+    "prepare": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.11.0",
+    "@types/eventsource": "^1.1.11"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "eventsource": "^2.0.2"
+  },
+  "peerDependencies": {
+    "homebridge": ">=1.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}