homebridge-mitsubishi-comfort 1.0.1 → 1.3.1

package/README.md

@@ -1,16 +1,27 @@
-# Homebridge Kumo v3 Plugin
+# Homebridge Mitsubishi Comfort
 
 A Homebridge plugin for Mitsubishi heat pumps using the Kumo Cloud v3 API.
 
+## ⚠️ Disclaimer
+
+This plugin is not affiliated with, endorsed by, or associated with Mitsubishi Electric in any way. It is an independent, unofficial plugin developed by the community for personal use.
+
+**Use at your own risk.** The author assumes no liability for any damage, data loss, or issues that may arise from using this plugin. By using this plugin, you acknowledge that you do so entirely at your own discretion and risk.
+
 ## Features
 
+- **Intelligent streaming-first architecture** with automatic fallback
+- **95% reduction in API calls** when streaming is healthy (optimal mode)
+- **Real-time streaming updates** via Socket.IO for instant status changes
+- **Adaptive polling** that activates only when streaming fails
 - Full HomeKit thermostat integration
 - Support for Heat, Cool, Auto, and Off modes
 - Temperature control
 - Current temperature and humidity display
 - Automatic token refresh
-- Status polling every 30 seconds
 - Multi-site and multi-zone support
+- Device exclusion/hiding support
+- Comprehensive logging for streaming/polling state transitions
 
 ## Installation
 
@@ -60,10 +71,68 @@ Add the following to your Homebridge `config.json`:
 | `name` | string | No | Platform name (default: "Kumo") |
 | `username` | string | Yes | Your Kumo Cloud email address |
 | `password` | string | Yes | Your Kumo Cloud password |
-| `pollInterval` | number | No | Status polling interval in seconds (default: 30) |
-| `excludeDevices` | string[] | No | Array of device serial numbers to exclude |
+| `pollInterval` | number | No | Polling interval when streaming is healthy in seconds (default: 30, minimum: 5) |
+| `disablePolling` | boolean | No | **Recommended:** Disable polling when streaming is healthy (auto-enables if streaming fails, default: false) |
+| `degradedPollInterval` | number | No | Fast polling interval when streaming is unhealthy in seconds (default: 10, minimum: 5, maximum: 60) |
+| `streamingHealthCheckInterval` | number | No | How often to check if streaming is healthy in seconds (default: 30, minimum: 10, maximum: 300) |
+| `streamingStaleThreshold` | number | No | Consider streaming stale if no updates received for this long in seconds (default: 60, minimum: 30, maximum: 600) |
+| `excludeDevices` | string[] | No | Array of device serial numbers to hide from HomeKit |
 | `debug` | boolean | No | Enable debug logging (default: false) |
 
+### Recommended Configuration for Optimal Efficiency
+
+For best performance and minimal network traffic, enable streaming-only mode:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "KumoV3",
+      "name": "Kumo",
+      "username": "your-email@example.com",
+      "password": "your-password",
+      "disablePolling": true
+    }
+  ]
+}
+```
+
+This configuration:
+- Uses streaming for all device updates when healthy (0 polling queries)
+- Automatically activates 10-second polling if streaming disconnects
+- Reduces API calls by ~95% (from ~257/hour to ~12/hour)
+- Only makes token refresh queries every 15 minutes during normal operation
+
+### Debug Mode
+
+When `debug: true` is enabled, the plugin will log detailed information including:
+
+- API requests and responses with timing information
+- Raw JSON data from zone/device API responses showing all available fields
+- Real-time streaming updates with complete device state
+- Authentication and token refresh events
+- WebSocket connection status
+
+**Note:** Debug mode may log sensitive information and should only be enabled for troubleshooting. The plugin will display a warning when debug mode is active.
+
+### Known Limitations
+
+- **Outdoor Temperature**: The Kumo Cloud API does not expose outdoor temperature data from the outdoor units. While outdoor units have temperature sensors (used for defrost cycles), this data is only available through direct CN105 serial connections, not through the cloud API.
+
+- **Temperature Display Differences**: Mitsubishi and Apple use different Fahrenheit-to-Celsius conversion tables, which can cause temperature setpoints to display differently in each app:
+
+  **When you set 70°F in Apple Home:**
+  - HomeKit converts using standard math: 70°F → 21.111°C
+  - Your unit is set to exactly 21.111°C (70.0°F)
+  - Mitsubishi Comfort app may display this as ~69°F due to their custom conversion table
+
+  **When you set 70°F in Mitsubishi Comfort app:**
+  - Mitsubishi converts using their custom table: 70°F → 21.5°C (0.5°C increments)
+  - Your unit is set to 21.5°C (which equals 70.7°F in standard conversion)
+  - Apple Home displays this as 71°F (because 21.5°C = 70.7°F)
+
+  **Both apps are technically correct** - they just use different conversion standards. The actual Celsius value sent to your unit is accurate in both cases. For consistency, pick one app for temperature control rather than mixing both.
+
 ## Development
 
 ### Build
@@ -85,8 +154,22 @@ This will compile TypeScript, link the plugin, and restart on changes.
 1. **Authentication**: The plugin logs in to the Kumo Cloud v3 API using your credentials
 2. **Token Management**: Access tokens are automatically refreshed every 15 minutes
 3. **Discovery**: All sites and zones are discovered and registered as HomeKit thermostats
-4. **Polling**: Device status is polled every 30 seconds to keep HomeKit in sync
-5. **Control**: Changes made in HomeKit are sent to the Kumo Cloud API
+4. **Real-time Streaming**: Establishes Socket.IO connection for instant device updates
+5. **Intelligent Fallback**:
+   - **Normal Mode** (streaming healthy): Updates via streaming only, minimal API calls
+   - **Degraded Mode** (streaming failed): Automatic fallback to fast polling (10s intervals)
+   - **Health Monitoring**: Continuous checking of streaming connection status
+   - **Automatic Recovery**: Returns to streaming-only mode when connection restored
+6. **Control**: Changes made in HomeKit are sent to the Kumo Cloud API
+
+### Update Strategy
+
+The plugin uses a smart streaming-first approach with automatic fallback:
+
+- **When streaming is healthy**: All device updates arrive via Socket.IO in real-time. If `disablePolling: true` is set, no polling occurs (optimal mode).
+- **When streaming disconnects**: Plugin automatically switches to degraded mode with fast polling (default: 10s intervals) to ensure devices remain responsive.
+- **When streaming reconnects**: Plugin automatically returns to normal mode, halting polling if `disablePolling: true`.
+- **Race condition prevention**: Timestamp-based filtering ensures newer updates always take precedence, regardless of source.
 
 ## Supported Characteristics
 
@@ -99,12 +182,18 @@ This will compile TypeScript, link the plugin, and restart on changes.
 
 ## API Endpoints Used
 
+### REST API
 - `POST /v3/login` - Authentication
 - `GET /v3/sites` - Get all sites
 - `GET /v3/sites/{siteId}/zones` - Get zones for a site
 - `GET /v3/devices/{deviceSerial}/status` - Get device status
 - `POST /v3/devices/send-command` - Send commands to device
 
+### Socket.IO Streaming
+- `wss://socket-prod.kumocloud.com` - Real-time device updates via Socket.IO
+- Emits `subscribe` event with device serial to receive updates
+- Receives `device_update` events with full device state
+
 ## Security
 
 ### Best Practices
@@ -143,7 +232,21 @@ This will compile TypeScript, link the plugin, and restart on changes.
 
 ## License
 
-MIT
+Apache License 2.0
+
+Copyright 2024
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
 
 ## Credits
 

package/config.schema.json

@@ -31,7 +31,13 @@
         "type": "integer",
         "default": 30,
         "minimum": 5,
-        "description": "How often to poll device status (minimum 5 seconds)"
+        "description": "Polling interval when streaming is healthy (minimum 5 seconds, default 30)"
+      },
+      "disablePolling": {
+        "title": "Disable Polling",
+        "type": "boolean",
+        "default": false,
+        "description": "Disable polling when streaming is healthy (will auto-enable if streaming fails)"
       },
       "debug": {
         "title": "Debug Mode",
@@ -40,13 +46,40 @@
         "description": "Enable verbose debug logging (requires running Homebridge with -D flag)"
       },
       "excludeDevices": {
-        "title": "Excluded Devices",
+        "title": "Hide Device IDs",
         "type": "array",
+        "uniqueItems": true,
         "items": {
           "type": "string",
-          "title": "Device Serial Number"
+          "title": "Device Serial Number",
+          "placeholder": "e.g., 9X34P008S100095F",
+          "description": "Enter device serial number to hide"
         },
-        "description": "List of device serial numbers to exclude from HomeKit"
+        "description": "Device serial numbers to hide from HomeKit (found in logs during device discovery)"
+      },
+      "streamingHealthCheckInterval": {
+        "title": "Streaming Health Check Interval (seconds)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 10,
+        "maximum": 300,
+        "description": "How often to check if streaming is healthy (default: 30 seconds)"
+      },
+      "streamingStaleThreshold": {
+        "title": "Streaming Stale Threshold (seconds)",
+        "type": "integer",
+        "default": 60,
+        "minimum": 30,
+        "maximum": 600,
+        "description": "Consider streaming stale if no updates received for this long (default: 60 seconds)"
+      },
+      "degradedPollInterval": {
+        "title": "Degraded Mode Poll Interval (seconds)",
+        "type": "integer",
+        "default": 10,
+        "minimum": 5,
+        "maximum": 60,
+        "description": "Fast polling interval when streaming is unhealthy (default: 10 seconds)"
       }
     }
   },
@@ -62,7 +95,26 @@
       "title": "Advanced Settings",
       "expandable": true,
       "expanded": false,
-      "items": ["pollInterval", "excludeDevices", "debug"]
+      "items": [
+        "pollInterval",
+        "degradedPollInterval",
+        "disablePolling",
+        "streamingHealthCheckInterval",
+        "streamingStaleThreshold",
+        {
+          "key": "excludeDevices",
+          "type": "array",
+          "title": "Hide Device IDs",
+          "buttonText": "Add Device Serial",
+          "items": [
+            {
+              "type": "string",
+              "placeholder": "e.g., 9X34P008S100095F"
+            }
+          ]
+        },
+        "debug"
+      ]
     }
   ]
 }

package/dist/accessory.d.ts

@@ -1,6 +1,7 @@
 import { PlatformAccessory, CharacteristicValue } from 'homebridge';
 import { KumoV3Platform } from './platform';
 import { KumoAPI } from './kumo-api';
+import { Zone } from './settings';
 export declare class KumoThermostatAccessory {
     private readonly platform;
     private readonly accessory;
@@ -12,9 +13,14 @@ export declare class KumoThermostatAccessory {
     private currentStatus;
     private pollIntervalMs;
     private hasHumiditySensor;
+    private lastUpdateTimestamp;
+    private lastUpdateSource;
     constructor(platform: KumoV3Platform, accessory: PlatformAccessory, kumoAPI: KumoAPI, pollIntervalSeconds?: number);
-    private startPolling;
-    private updateStatus;
+    private handleStreamingUpdate;
+    getSiteId(): string;
+    getDeviceSerial(): string;
+    updateFromZone(zone: Zone): void;
+    private processZoneUpdate;
     private mapToCurrentHeatingCoolingState;
     private mapToTargetHeatingCoolingState;
     private getTargetTempFromStatus;
@@ -24,8 +30,6 @@ export declare class KumoThermostatAccessory {
     getCurrentTemperature(): Promise<CharacteristicValue>;
     getTargetTemperature(): Promise<CharacteristicValue>;
     setTargetTemperature(value: CharacteristicValue): Promise<void>;
-    getTemperatureDisplayUnits(): Promise<CharacteristicValue>;
-    setTemperatureDisplayUnits(value: CharacteristicValue): Promise<void>;
     getCurrentRelativeHumidity(): Promise<CharacteristicValue>;
     destroy(): void;
 }

package/dist/accessory.js

@@ -10,6 +10,8 @@ class KumoThermostatAccessory {
         this.pollTimer = null;
         this.currentStatus = null;
         this.hasHumiditySensor = false;
+        this.lastUpdateTimestamp = 0;
+        this.lastUpdateSource = 'none';
         this.deviceSerial = this.accessory.context.device.deviceSerial;
         this.siteId = this.accessory.context.device.siteId;
         this.pollIntervalMs = (pollIntervalSeconds || settings_1.POLL_INTERVAL / 1000) * 1000;
@@ -30,29 +32,65 @@ class KumoThermostatAccessory {
         this.service.getCharacteristic(this.platform.Characteristic.TargetTemperature)
             .onGet(this.getTargetTemperature.bind(this))
             .onSet(this.setTargetTemperature.bind(this));
-        this.service.getCharacteristic(this.platform.Characteristic.TemperatureDisplayUnits)
-            .onGet(this.getTemperatureDisplayUnits.bind(this))
-            .onSet(this.setTemperatureDisplayUnits.bind(this));
-        this.startPolling();
+        this.kumoAPI.subscribeToDevice(this.deviceSerial, this.handleStreamingUpdate.bind(this));
+        this.platform.log.debug(`Registered streaming callback for ${this.deviceSerial}`);
     }
-    startPolling() {
-        this.updateStatus();
-        this.pollTimer = setInterval(() => {
-            this.updateStatus();
-        }, this.pollIntervalMs);
+    handleStreamingUpdate(deviceSerial, data) {
+        if (data.roomTemp === undefined || data.roomTemp === null) {
+            this.platform.log.debug(`Streaming update for ${deviceSerial} missing essential data, skipping`);
+            return;
+        }
+        const updateTimestamp = Date.now();
+        this.platform.log.debug(`Streaming update received for ${deviceSerial}: temp=${data.roomTemp}, mode=${data.operationMode}, power=${data.power}`);
+        const zoneUpdate = {
+            adapter: {
+                id: data.id || '',
+                deviceSerial: deviceSerial,
+                roomTemp: data.roomTemp,
+                spHeat: data.spHeat,
+                spCool: data.spCool,
+                spAuto: data.spAuto || null,
+                humidity: data.humidity || null,
+                power: data.power,
+                operationMode: data.operationMode,
+                previousOperationMode: data.operationMode,
+                fanSpeed: data.fanSpeed || 'auto',
+                airDirection: data.airDirection || 'auto',
+                connected: true,
+                isSimulator: false,
+                hasSensor: data.humidity !== null && data.humidity !== undefined,
+                hasMhk2: false,
+                scheduleOwner: 'adapter',
+                scheduleHoldEndTime: 0,
+                rssi: data.rssi,
+            },
+        };
+        this.processZoneUpdate(zoneUpdate, 'streaming', updateTimestamp);
+    }
+    getSiteId() {
+        return this.siteId;
+    }
+    getDeviceSerial() {
+        return this.deviceSerial;
     }
-    async updateStatus(forceRefresh = false) {
+    updateFromZone(zone) {
+        const updateTimestamp = Date.now();
+        this.processZoneUpdate(zone, 'polling', updateTimestamp);
+    }
+    processZoneUpdate(zone, source, timestamp) {
         try {
-            const result = await this.kumoAPI.getZonesWithETag(this.siteId, forceRefresh);
-            if (result.notModified) {
-                this.platform.log.debug(`Status not modified for device ${this.deviceSerial}`);
+            if (timestamp < this.lastUpdateTimestamp) {
+                this.platform.log.debug(`[${this.deviceSerial}] Ignoring ${source} update: ` +
+                    `${this.lastUpdateTimestamp - timestamp}ms older than last ${this.lastUpdateSource} update`);
                 return;
             }
-            const zone = result.zones.find(z => z.adapter.deviceSerial === this.deviceSerial);
-            if (!zone) {
-                this.platform.log.error(`Device ${this.deviceSerial} not found in zones response`);
-                return;
+            this.lastUpdateTimestamp = timestamp;
+            const previousSource = this.lastUpdateSource;
+            this.lastUpdateSource = source;
+            if (previousSource !== source && previousSource !== 'none') {
+                this.platform.log.debug(`[${this.deviceSerial}] Update source changed: ${previousSource} → ${source}`);
             }
+            this.platform.log.debug(`Processing ${source} update for ${this.deviceSerial}`);
             if (zone.adapter.roomTemp === undefined || zone.adapter.roomTemp === null) {
                 this.platform.log.error(`Device ${this.deviceSerial} has invalid roomTemp: ${zone.adapter.roomTemp}`);
                 this.platform.log.debug('Zone adapter data:', JSON.stringify(zone.adapter));
@@ -87,7 +125,7 @@ class KumoThermostatAccessory {
                 spAuto: zone.adapter.spAuto,
             };
             this.currentStatus = status;
-            this.platform.log.debug(`Updated status for ${this.deviceSerial}: roomTemp=${status.roomTemp}, mode=${status.operationMode}`);
+            this.platform.log.debug(`${this.accessory.displayName}: ${status.roomTemp}°C (target: ${this.getTargetTempFromStatus(status)}°C, mode: ${status.operationMode})`);
             this.service.updateCharacteristic(this.platform.Characteristic.CurrentHeatingCoolingState, this.mapToCurrentHeatingCoolingState(status));
             this.service.updateCharacteristic(this.platform.Characteristic.TargetHeatingCoolingState, this.mapToTargetHeatingCoolingState(status));
             if (status.roomTemp !== undefined && status.roomTemp !== null && !isNaN(status.roomTemp)) {
@@ -95,6 +133,8 @@ class KumoThermostatAccessory {
             }
             const targetTemp = this.getTargetTempFromStatus(status);
             if (targetTemp !== undefined && targetTemp !== null && !isNaN(targetTemp)) {
+                const targetTempF = (targetTemp * 9 / 5) + 32;
+                this.platform.log.debug(`[TEMP UPDATE] ${this.accessory.displayName}: API returned target ${targetTemp.toFixed(3)}°C (${targetTempF.toFixed(1)}°F) [mode: ${status.operationMode}]`);
                 this.service.updateCharacteristic(this.platform.Characteristic.TargetTemperature, targetTemp);
             }
             if (this.hasHumiditySensor && status.humidity !== null) {
@@ -189,31 +229,41 @@ class KumoThermostatAccessory {
     async setTargetHeatingCoolingState(value) {
         this.platform.log.debug('Set TargetHeatingCoolingState:', value);
         let operationMode;
+        let modeName;
         switch (value) {
             case this.platform.Characteristic.TargetHeatingCoolingState.OFF:
                 operationMode = 'off';
+                modeName = 'OFF';
                 break;
             case this.platform.Characteristic.TargetHeatingCoolingState.HEAT:
                 operationMode = 'heat';
+                modeName = 'HEAT';
                 break;
             case this.platform.Characteristic.TargetHeatingCoolingState.COOL:
                 operationMode = 'cool';
+                modeName = 'COOL';
                 break;
             case this.platform.Characteristic.TargetHeatingCoolingState.AUTO:
                 operationMode = 'auto';
+                modeName = 'AUTO';
                 break;
             default:
                 this.platform.log.error('Unknown target heating cooling state:', value);
                 return;
         }
+        this.platform.log.info(`[MODE CHANGE] ${this.accessory.displayName}: HomeKit sent ${modeName} mode`);
         const success = await this.kumoAPI.sendCommand(this.deviceSerial, {
             operationMode,
         });
         if (success) {
-            setTimeout(() => this.updateStatus(true), 1000);
+            this.platform.log.info(`[MODE CHANGE] ${this.accessory.displayName}: Command accepted by API`);
+            if (this.currentStatus) {
+                this.currentStatus.operationMode = operationMode;
+                this.currentStatus.power = operationMode === 'off' ? 0 : 1;
+            }
         }
         else {
-            this.platform.log.error(`Failed to set target heating cooling state for ${this.accessory.displayName}`);
+            this.platform.log.error(`[MODE CHANGE] ${this.accessory.displayName}: Failed to set mode to ${modeName}`);
         }
     }
     async getCurrentTemperature() {
@@ -223,16 +273,18 @@ class KumoThermostatAccessory {
                 this.currentStatus = status;
             }
             else {
-                this.platform.log.warn('No status available for getCurrentTemperature');
+                this.platform.log.debug('No status available yet for getCurrentTemperature, returning default');
                 return 20;
             }
         }
         const temp = this.currentStatus.roomTemp;
         if (temp === undefined || temp === null || isNaN(temp)) {
-            this.platform.log.warn('Invalid roomTemp value:', temp);
+            if (this.lastUpdateSource !== 'none') {
+                this.platform.log.warn(`Invalid roomTemp value for ${this.accessory.displayName}:`, temp);
+            }
             return 20;
         }
-        this.platform.log.debug('Get CurrentTemperature:', temp);
+        this.platform.log.debug(`HomeKit get current temp for ${this.accessory.displayName}: ${temp}°C`);
         return temp;
     }
     async getTargetTemperature() {
@@ -242,55 +294,60 @@ class KumoThermostatAccessory {
                 this.currentStatus = status;
             }
             else {
-                this.platform.log.warn('No status available for getTargetTemperature');
+                this.platform.log.debug('No status available yet for getTargetTemperature, returning default');
                 return 20;
             }
         }
         const temp = this.getTargetTempFromStatus(this.currentStatus);
         if (temp === undefined || temp === null || isNaN(temp)) {
-            this.platform.log.warn('Invalid target temperature value:', temp);
+            if (this.lastUpdateSource !== 'none') {
+                this.platform.log.warn(`Invalid target temperature value for ${this.accessory.displayName}:`, temp);
+            }
             return 20;
         }
-        this.platform.log.debug('Get TargetTemperature:', temp);
+        this.platform.log.debug(`HomeKit get target temp for ${this.accessory.displayName}: ${temp}°C`);
         return temp;
     }
     async setTargetTemperature(value) {
         const temp = value;
-        this.platform.log.debug('Set TargetTemperature:', temp);
+        const tempF = (temp * 9 / 5) + 32;
+        this.platform.log.info(`[TEMP CHANGE] ${this.accessory.displayName}: HomeKit sent ${temp.toFixed(3)}°C (${tempF.toFixed(1)}°F)`);
         if (!this.currentStatus) {
             this.platform.log.error('Cannot set temperature - no current status');
             return;
         }
-        const roundedTemp = Math.round(temp * 2) / 2;
-        this.platform.log.debug(`Rounded temperature from ${temp} to ${roundedTemp}`);
         const commands = {};
         if (this.currentStatus.operationMode === 'heat') {
-            commands.spHeat = roundedTemp;
+            commands.spHeat = temp;
         }
         else if (this.currentStatus.operationMode === 'cool') {
-            commands.spCool = roundedTemp;
+            commands.spCool = temp;
         }
         else if (this.currentStatus.operationMode === 'auto') {
-            commands.spHeat = roundedTemp;
-            commands.spCool = roundedTemp;
+            commands.spHeat = temp;
+            commands.spCool = temp;
         }
         else {
-            commands.spHeat = roundedTemp;
+            commands.spHeat = temp;
         }
+        this.platform.log.info(`[TEMP CHANGE] ${this.accessory.displayName}: Sending to API: ${JSON.stringify(commands)}°C`);
         const success = await this.kumoAPI.sendCommand(this.deviceSerial, commands);
         if (success) {
-            setTimeout(() => this.updateStatus(true), 1000);
+            this.platform.log.info(`[TEMP CHANGE] ${this.accessory.displayName}: Command accepted by API`);
+            if (this.currentStatus) {
+                if (commands.spHeat !== undefined) {
+                    this.currentStatus.spHeat = commands.spHeat;
+                }
+                if (commands.spCool !== undefined) {
+                    this.currentStatus.spCool = commands.spCool;
+                }
+            }
+            this.service.updateCharacteristic(this.platform.Characteristic.TargetTemperature, temp);
         }
         else {
             this.platform.log.error(`Failed to set target temperature for ${this.accessory.displayName}: ${JSON.stringify(commands)}`);
         }
     }
-    async getTemperatureDisplayUnits() {
-        return this.platform.Characteristic.TemperatureDisplayUnits.CELSIUS;
-    }
-    async setTemperatureDisplayUnits(value) {
-        this.platform.log.debug('Set TemperatureDisplayUnits:', value);
-    }
     async getCurrentRelativeHumidity() {
         var _a;
         if (!this.currentStatus) {
@@ -304,10 +361,8 @@ class KumoThermostatAccessory {
         return humidity;
     }
     destroy() {
-        if (this.pollTimer) {
-            clearInterval(this.pollTimer);
-            this.pollTimer = null;
-        }
+        this.kumoAPI.unsubscribeFromDevice(this.deviceSerial);
+        this.platform.log.debug(`Unsubscribed from streaming updates for ${this.deviceSerial}`);
     }
 }
 exports.KumoThermostatAccessory = KumoThermostatAccessory;

package/dist/kumo-api.d.ts

@@ -1,5 +1,6 @@
 import type { Logger } from 'homebridge';
 import { Site, Zone, DeviceStatus, Commands } from './settings';
+export type DeviceUpdateCallback = (deviceSerial: string, status: Partial<DeviceStatus>) => void;
 export declare class KumoAPI {
     private readonly username;
     private readonly password;
@@ -8,9 +9,20 @@ export declare class KumoAPI {
     private refreshToken;
     private tokenExpiresAt;
     private refreshTimer;
-    private siteEtags;
     private debugMode;
-    constructor(username: string, password: string, log: Logger, debug?: boolean);
+    private refreshInProgress;
+    private socket;
+    private streamingEnabled;
+    private deviceUpdateCallbacks;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private lastStreamingUpdate;
+    private streamingHealthCallbacks;
+    private healthCheckTimer;
+    private streamingHealthCheckInterval;
+    private streamingStaleThreshold;
+    private isStreamingHealthy;
+    constructor(username: string, password: string, log: Logger, debug?: boolean, enableStreaming?: boolean);
     private maskToken;
     login(): Promise<boolean>;
     private scheduleTokenRefresh;
@@ -20,11 +32,19 @@ export declare class KumoAPI {
     private makeAuthenticatedRequest;
     getSites(): Promise<Site[]>;
     getZones(siteId: string): Promise<Zone[]>;
-    getZonesWithETag(siteId: string, forceRefresh?: boolean): Promise<{
-        zones: Zone[];
-        notModified: boolean;
-    }>;
     getDeviceStatus(deviceSerial: string): Promise<DeviceStatus | null>;
     sendCommand(deviceSerial: string, commands: Commands): Promise<boolean>;
+    startStreaming(deviceSerials: string[]): Promise<boolean>;
+    subscribeToDevice(deviceSerial: string, callback: DeviceUpdateCallback): void;
+    unsubscribeFromDevice(deviceSerial: string): void;
+    isStreamingConnected(): boolean;
+    setStreamingHealthConfig(checkInterval: number, staleThreshold: number): void;
+    onStreamingHealthChange(callback: (isHealthy: boolean) => void): void;
+    getStreamingHealth(): boolean;
+    private updateStreamingTimestamp;
+    private checkStreamingHealth;
+    private notifyHealthChange;
+    private startHealthChecks;
+    private stopHealthChecks;
     destroy(): void;
 }

package/dist/kumo-api.js

@@ -5,9 +5,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KumoAPI = void 0;
 const node_fetch_1 = __importDefault(require("node-fetch"));
+const socket_io_client_1 = require("socket.io-client");
 const settings_1 = require("./settings");
 class KumoAPI {
-    constructor(username, password, log, debug = false) {
+    constructor(username, password, log, debug = false, enableStreaming = true) {
         this.username = username;
         this.password = password;
         this.log = log;
@@ -15,13 +16,28 @@ class KumoAPI {
         this.refreshToken = null;
         this.tokenExpiresAt = 0;
         this.refreshTimer = null;
-        this.siteEtags = new Map();
         this.debugMode = false;
+        this.refreshInProgress = null;
+        this.socket = null;
+        this.streamingEnabled = true;
+        this.deviceUpdateCallbacks = new Map();
+        this.reconnectAttempts = 0;
+        this.maxReconnectAttempts = 5;
+        this.lastStreamingUpdate = new Map();
+        this.streamingHealthCallbacks = new Set();
+        this.healthCheckTimer = null;
+        this.streamingHealthCheckInterval = 30000;
+        this.streamingStaleThreshold = 60000;
+        this.isStreamingHealthy = false;
         this.debugMode = debug;
+        this.streamingEnabled = enableStreaming;
         if (this.debugMode) {
             this.log.info('Debug mode enabled');
             this.log.warn('Debug mode may log sensitive information - use only for troubleshooting');
         }
+        if (this.streamingEnabled) {
+            this.log.info('Streaming mode enabled - real-time updates will be used');
+        }
     }
     maskToken(token) {
         if (!token) {
@@ -99,17 +115,21 @@ class KumoAPI {
                 headers: {
                     'Content-Type': 'application/json',
                     'Accept': 'application/json',
-                    'Authorization': `Bearer ${this.refreshToken}`,
                     'X-App-Version': settings_1.APP_VERSION,
                 },
+                body: JSON.stringify({
+                    refresh: this.refreshToken,
+                }),
             });
             if (!response.ok) {
-                this.log.warn('Token refresh failed, attempting full login');
+                const errorText = await response.text();
+                this.log.warn(`Token refresh failed (${response.status}): ${errorText}`);
+                this.log.warn('Attempting full login');
                 return await this.login();
             }
             const data = await response.json();
-            this.accessToken = data.token.access;
-            this.refreshToken = data.token.refresh;
+            this.accessToken = data.access;
+            this.refreshToken = data.refresh;
             this.tokenExpiresAt = Date.now() + settings_1.TOKEN_REFRESH_INTERVAL;
             this.log.debug('Access token refreshed successfully');
             this.scheduleTokenRefresh();
@@ -127,10 +147,22 @@ class KumoAPI {
     }
     async ensureAuthenticated() {
         if (!this.accessToken || Date.now() >= this.tokenExpiresAt - (5 * 60 * 1000)) {
-            if (!this.refreshToken) {
-                return await this.login();
+            if (this.refreshInProgress) {
+                this.log.debug('Waiting for existing token refresh to complete');
+                return await this.refreshInProgress;
             }
-            return await this.refreshAccessToken();
+            this.refreshInProgress = (async () => {
+                try {
+                    if (!this.refreshToken) {
+                        return await this.login();
+                    }
+                    return await this.refreshAccessToken();
+                }
+                finally {
+                    this.refreshInProgress = null;
+                }
+            })();
+            return await this.refreshInProgress;
         }
         return true;
     }
@@ -156,7 +188,16 @@ class KumoAPI {
             if (body) {
                 options.body = JSON.stringify(body);
             }
-            const response = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}${endpoint}`, options);
+            const url = `${settings_1.API_BASE_URL}${endpoint}`;
+            if (this.debugMode) {
+                this.log.info(`→ API Request: ${method} ${endpoint}`);
+                if (body) {
+                    this.log.info(`  Body: ${JSON.stringify(body)}`);
+                }
+            }
+            const startTime = Date.now();
+            const response = await (0, node_fetch_1.default)(url, options);
+            const duration = Date.now() - startTime;
             if (response.status === 401) {
                 this.log.debug('Received 401, refreshing token and retrying');
                 const refreshed = await this.refreshAccessToken();
@@ -173,9 +214,23 @@ class KumoAPI {
             }
             if (!response.ok) {
                 this.log.error(`Request failed with status: ${response.status}`);
+                const errorText = await response.text();
+                if (this.debugMode || response.status === 400) {
+                    this.log.error(`  Error response: ${errorText}`);
+                }
                 return null;
             }
-            return await response.json();
+            const data = await response.json();
+            if (this.debugMode) {
+                this.log.info(`← API Response: ${response.status} (${duration}ms)`);
+                if (Array.isArray(data)) {
+                    this.log.info(`  Returned ${data.length} item(s)`);
+                }
+                else if (data && typeof data === 'object') {
+                    this.log.info(`  Keys: ${Object.keys(data).join(', ')}`);
+                }
+            }
+            return data;
         }
         catch (error) {
             if (error instanceof Error) {
@@ -196,58 +251,63 @@ class KumoAPI {
         return sites || [];
     }
     async getZones(siteId) {
-        this.log.debug(`Fetching zones for site: ${siteId}`);
-        const zones = await this.makeAuthenticatedRequest(`/sites/${siteId}/zones`);
-        return zones || [];
-    }
-    async getZonesWithETag(siteId, forceRefresh = false) {
-        const etag = this.siteEtags.get(siteId);
         const authenticated = await this.ensureAuthenticated();
         if (!authenticated) {
             this.log.error('Failed to authenticate');
-            return { zones: [], notModified: false };
+            return [];
         }
         try {
-            const headers = this.getAuthHeaders();
-            if (etag && !forceRefresh) {
-                headers['If-None-Match'] = etag;
-            }
-            const response = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}/sites/${siteId}/zones`, { headers });
-            if (response.status === 304) {
-                this.log.debug(`Zones for site ${siteId}: Not Modified (304)`);
-                return { zones: [], notModified: true };
+            const endpoint = `/sites/${siteId}/zones`;
+            if (this.debugMode) {
+                this.log.info(`→ API Request: GET ${endpoint}`);
             }
+            const startTime = Date.now();
+            const response = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}${endpoint}`, {
+                headers: this.getAuthHeaders(),
+            });
+            const duration = Date.now() - startTime;
             if (!response.ok) {
                 const errorBody = await response.text();
                 this.log.error(`Failed to fetch zones for site ${siteId}: ${response.status} - ${errorBody}`);
-                return { zones: [], notModified: false };
-            }
-            const newEtag = response.headers.get('etag');
-            if (newEtag) {
-                this.siteEtags.set(siteId, newEtag);
+                return [];
             }
             const zones = await response.json();
             if (this.debugMode) {
-                this.log.debug(`Fetched ${zones.length} zones for site ${siteId}`);
+                this.log.info(`← API Response: 200 (${duration}ms)`);
+                this.log.info(`  Fetched ${zones.length} zone(s) for site ${siteId}`);
+                zones.forEach(zone => {
+                    this.log.info(`  RAW Zone JSON for ${zone.name}:`);
+                    this.log.info(JSON.stringify(zone, null, 2));
+                });
                 zones.forEach(zone => {
-                    this.log.debug(`Zone ${zone.name} (${zone.adapter.deviceSerial}): roomTemp=${zone.adapter.roomTemp}`);
+                    const a = zone.adapter;
+                    this.log.info(`    ${zone.name} [${a.deviceSerial}]`);
+                    this.log.info(`      Temperature: ${a.roomTemp}°C (current) → Heat: ${a.spHeat}°C, Cool: ${a.spCool}°C, Auto: ${a.spAuto}°C`);
+                    this.log.info(`      Status: ${a.operationMode} mode, power=${a.power}, connected=${a.connected}`);
+                    this.log.info(`      Fan: ${a.fanSpeed}, Direction: ${a.airDirection}, Humidity: ${a.humidity !== null ? a.humidity + '%' : 'N/A'}`);
+                    this.log.info(`      Signal: ${a.rssi !== undefined ? a.rssi + ' dBm' : 'N/A'}`);
                 });
             }
-            return { zones, notModified: false };
+            return zones;
         }
         catch (error) {
             if (error instanceof Error) {
-                this.log.error('Error fetching zones with ETag:', error.message);
+                this.log.error('Error fetching zones:', error.message);
             }
             else {
                 this.log.error('Error fetching zones: Unknown error occurred');
             }
-            return { zones: [], notModified: false };
+            return [];
         }
     }
     async getDeviceStatus(deviceSerial) {
         this.log.debug(`Fetching status for device: ${deviceSerial}`);
-        return await this.makeAuthenticatedRequest(`/devices/${deviceSerial}/status`);
+        const status = await this.makeAuthenticatedRequest(`/devices/${deviceSerial}/status`);
+        if (this.debugMode && status) {
+            this.log.info(`  RAW Device Status JSON for ${deviceSerial}:`);
+            this.log.info(JSON.stringify(status, null, 2));
+        }
+        return status;
     }
     async sendCommand(deviceSerial, commands) {
         this.log.debug(`Sending command to device ${deviceSerial}:`, JSON.stringify(commands));
@@ -274,11 +334,160 @@ class KumoAPI {
         this.log.debug(`Command sent successfully to device ${deviceSerial}`);
         return true;
     }
+    async startStreaming(deviceSerials) {
+        var _a;
+        if (!this.streamingEnabled) {
+            this.log.debug('Streaming is disabled, skipping connection');
+            return false;
+        }
+        if ((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected) {
+            this.log.debug('Streaming already connected');
+            return true;
+        }
+        if (!this.accessToken) {
+            this.log.error('Cannot start streaming: not authenticated');
+            return false;
+        }
+        try {
+            this.log.info('Starting streaming connection...');
+            this.socket = (0, socket_io_client_1.io)(settings_1.SOCKET_BASE_URL, {
+                transports: ['polling', 'websocket'],
+                extraHeaders: {
+                    'Authorization': `Bearer ${this.accessToken}`,
+                    'Accept': '*/*',
+                    'User-Agent': 'kumocloud/1122',
+                },
+            });
+            this.socket.on('connect', () => {
+                var _a, _b;
+                this.log.info(`✓ Streaming connected (ID: ${(_a = this.socket) === null || _a === void 0 ? void 0 : _a.id})`);
+                this.reconnectAttempts = 0;
+                for (const deviceSerial of deviceSerials) {
+                    this.log.debug(`Subscribing to device: ${deviceSerial}`);
+                    (_b = this.socket) === null || _b === void 0 ? void 0 : _b.emit('subscribe', deviceSerial);
+                }
+                for (const deviceSerial of deviceSerials) {
+                    this.lastStreamingUpdate.set(deviceSerial, Date.now());
+                }
+                this.isStreamingHealthy = true;
+                this.notifyHealthChange(false, true);
+                this.startHealthChecks();
+                this.log.info('✓ Streaming connection established');
+                this.log.info(`Monitoring ${deviceSerials.length} device(s) for real-time updates`);
+            });
+            this.socket.on('device_update', (data) => {
+                const deviceSerial = data.deviceSerial;
+                if (!deviceSerial) {
+                    return;
+                }
+                this.updateStreamingTimestamp(deviceSerial);
+                if (this.debugMode) {
+                    this.log.debug(`Stream update for ${deviceSerial}: temp=${data.roomTemp}°C, mode=${data.operationMode}, power=${data.power}`);
+                    this.log.info(`  RAW Streaming Update JSON for ${deviceSerial}:`);
+                    this.log.info(JSON.stringify(data, null, 2));
+                }
+                const callback = this.deviceUpdateCallbacks.get(deviceSerial);
+                if (callback) {
+                    callback(deviceSerial, data);
+                }
+            });
+            this.socket.on('disconnect', (reason) => {
+                this.log.warn(`✗ Streaming disconnected: ${reason}`);
+                const wasHealthy = this.isStreamingHealthy;
+                this.isStreamingHealthy = false;
+                this.notifyHealthChange(wasHealthy, false);
+                this.stopHealthChecks();
+                if (reason !== 'io client disconnect' && this.reconnectAttempts < this.maxReconnectAttempts) {
+                    this.reconnectAttempts++;
+                    this.log.info(`Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);
+                }
+                else if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+                    this.log.error('Max reconnect attempts reached - polling will handle updates');
+                }
+            });
+            this.socket.on('connect_error', (error) => {
+                this.log.error(`Streaming connection error: ${error.message}`);
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.log.error('Failed to start streaming:', error.message);
+            }
+            return false;
+        }
+    }
+    subscribeToDevice(deviceSerial, callback) {
+        var _a;
+        this.deviceUpdateCallbacks.set(deviceSerial, callback);
+        if ((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected) {
+            this.log.debug(`Subscribing to device: ${deviceSerial}`);
+            this.socket.emit('subscribe', deviceSerial);
+        }
+    }
+    unsubscribeFromDevice(deviceSerial) {
+        this.deviceUpdateCallbacks.delete(deviceSerial);
+    }
+    isStreamingConnected() {
+        var _a;
+        return ((_a = this.socket) === null || _a === void 0 ? void 0 : _a.connected) || false;
+    }
+    setStreamingHealthConfig(checkInterval, staleThreshold) {
+        this.streamingHealthCheckInterval = checkInterval * 1000;
+        this.streamingStaleThreshold = staleThreshold * 1000;
+        this.log.debug(`Streaming health config: check every ${checkInterval}s, stale after ${staleThreshold}s`);
+    }
+    onStreamingHealthChange(callback) {
+        this.streamingHealthCallbacks.add(callback);
+    }
+    getStreamingHealth() {
+        return this.isStreamingHealthy;
+    }
+    updateStreamingTimestamp(deviceSerial) {
+        this.lastStreamingUpdate.set(deviceSerial, Date.now());
+    }
+    checkStreamingHealth() {
+        const wasHealthy = this.isStreamingHealthy;
+        this.isStreamingHealthy = this.isStreamingConnected();
+        this.notifyHealthChange(wasHealthy, this.isStreamingHealthy);
+    }
+    notifyHealthChange(wasHealthy, isHealthy) {
+        if (wasHealthy !== isHealthy) {
+            this.log.info(`Streaming health changed: ${wasHealthy ? 'healthy' : 'unhealthy'} → ${isHealthy ? 'healthy' : 'unhealthy'}`);
+            for (const callback of this.streamingHealthCallbacks) {
+                callback(isHealthy);
+            }
+        }
+    }
+    startHealthChecks() {
+        if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+        }
+        this.healthCheckTimer = setInterval(() => {
+            this.checkStreamingHealth();
+        }, this.streamingHealthCheckInterval);
+        this.log.debug('Started streaming health checks');
+    }
+    stopHealthChecks() {
+        if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+            this.healthCheckTimer = null;
+        }
+    }
     destroy() {
         if (this.refreshTimer) {
             clearTimeout(this.refreshTimer);
             this.refreshTimer = null;
         }
+        this.stopHealthChecks();
+        this.streamingHealthCallbacks.clear();
+        this.lastStreamingUpdate.clear();
+        this.log.debug('Streaming health monitoring stopped');
+        if (this.socket) {
+            this.log.debug('Disconnecting streaming connection');
+            this.socket.disconnect();
+            this.socket = null;
+        }
     }
 }
 exports.KumoAPI = KumoAPI;

package/dist/platform.d.ts

@@ -9,8 +9,20 @@ export declare class KumoV3Platform implements DynamicPlatformPlugin {
     private readonly accessoryHandlers;
     private readonly kumoAPI;
     private readonly kumoConfig;
+    private readonly sitePollers;
+    private readonly siteAccessories;
+    private readonly degradedPollInterval;
+    private isStreamingHealthy;
+    private isDegradedMode;
     constructor(log: Logger, config: PlatformConfig, api: API);
     private cleanup;
     configureAccessory(accessory: PlatformAccessory): void;
     discoverDevices(): Promise<void>;
+    private startSitePoller;
+    private pollSite;
+    private handleStreamingHealthChange;
+    private enterDegradedMode;
+    private exitDegradedMode;
+    private restartAllPollers;
+    private stopAllPollers;
 }

package/dist/platform.js

@@ -13,6 +13,10 @@ class KumoV3Platform {
         this.Characteristic = this.api.hap.Characteristic;
         this.accessories = [];
         this.accessoryHandlers = [];
+        this.sitePollers = new Map();
+        this.siteAccessories = new Map();
+        this.isStreamingHealthy = false;
+        this.isDegradedMode = false;
         this.kumoConfig = config;
         this.log.debug('Initializing platform:', this.config.name);
         const kumoConfig = this.kumoConfig;
@@ -34,7 +38,15 @@ class KumoV3Platform {
                 throw new Error('Invalid poll interval');
             }
         }
+        this.degradedPollInterval = (kumoConfig.degradedPollInterval || 10) * 1000;
+        this.log.debug(`Degraded polling interval: ${this.degradedPollInterval / 1000}s`);
         this.kumoAPI = new kumo_api_1.KumoAPI(kumoConfig.username, kumoConfig.password, this.log, kumoConfig.debug || false);
+        const healthCheckInterval = kumoConfig.streamingHealthCheckInterval || 30;
+        const staleThreshold = kumoConfig.streamingStaleThreshold || 60;
+        this.kumoAPI.setStreamingHealthConfig(healthCheckInterval, staleThreshold);
+        this.kumoAPI.onStreamingHealthChange((isHealthy) => {
+            this.handleStreamingHealthChange(isHealthy);
+        });
         this.api.on('didFinishLaunching', () => {
             log.debug('Executed didFinishLaunching callback');
             this.discoverDevices();
@@ -45,6 +57,11 @@ class KumoV3Platform {
         });
     }
     cleanup() {
+        for (const [siteId, timer] of this.sitePollers) {
+            clearInterval(timer);
+            this.log.debug(`Stopped site poller for ${siteId}`);
+        }
+        this.sitePollers.clear();
         for (const handler of this.accessoryHandlers) {
             handler.destroy();
         }
@@ -82,7 +99,7 @@ class KumoV3Platform {
                     const deviceSerial = zone.adapter.deviceSerial;
                     const displayName = zone.name;
                     if ((_a = this.kumoConfig.excludeDevices) === null || _a === void 0 ? void 0 : _a.includes(deviceSerial)) {
-                        this.log.info(`Skipping excluded device: ${displayName} (${deviceSerial})`);
+                        this.log.info(`Hiding device from HomeKit: ${displayName} (${deviceSerial})`);
                         continue;
                     }
                     const uuid = this.api.hap.uuid.generate(deviceSerial);
@@ -128,10 +145,164 @@ class KumoV3Platform {
                 this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, staleAccessories);
             }
             this.log.info('Device discovery completed');
+            const allDeviceSerials = discoveredDevices.map(d => d.deviceSerial);
+            if (allDeviceSerials.length > 0) {
+                this.log.info('Starting streaming for real-time updates...');
+                const streamingStarted = await this.kumoAPI.startStreaming(allDeviceSerials);
+                if (streamingStarted) {
+                    this.log.info('✓ Streaming enabled - devices will update in real-time');
+                }
+                else {
+                    this.log.warn('Streaming failed to start - falling back to polling');
+                }
+                const healthCheckInterval = this.kumoConfig.streamingHealthCheckInterval || 30;
+                const staleThreshold = this.kumoConfig.streamingStaleThreshold || 60;
+                this.log.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+                this.log.info('Mitsubishi Comfort Plugin Configuration');
+                this.log.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+                this.log.info(`Streaming: ${streamingStarted ? 'ENABLED' : 'DISABLED'}`);
+                this.log.info(`Polling mode: ${this.kumoConfig.disablePolling ? 'On-demand only' : 'Enabled'}`);
+                this.log.info(`Normal poll interval: ${(this.kumoConfig.pollInterval || 30)}s`);
+                this.log.info(`Degraded poll interval: ${this.degradedPollInterval / 1000}s`);
+                this.log.info(`Health check interval: ${healthCheckInterval}s`);
+                this.log.info(`Stale threshold: ${staleThreshold}s`);
+                this.log.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+                if (streamingStarted) {
+                    if (this.kumoConfig.disablePolling) {
+                        this.log.info('Strategy: Streaming primary, polling fallback only');
+                    }
+                    else {
+                        this.log.info('Strategy: Streaming primary, polling supplemental');
+                    }
+                }
+            }
+            if (!this.kumoConfig.disablePolling) {
+                const uniqueSites = new Set(discoveredDevices.map(d => { var _a; return (_a = this.accessories.find(a => a.UUID === d.uuid)) === null || _a === void 0 ? void 0 : _a.context.device.siteId; }).filter(Boolean));
+                this.log.info(`Initializing pollers for ${uniqueSites.size} site(s)`);
+                for (const siteId of uniqueSites) {
+                    this.startSitePoller(siteId);
+                }
+            }
+            else {
+                this.log.info('Polling disabled - will activate only if streaming fails');
+            }
         }
         catch (error) {
             this.log.error('Error during device discovery:', error);
         }
     }
+    startSitePoller(siteId) {
+        if (this.sitePollers.has(siteId)) {
+            return;
+        }
+        if (this.isStreamingHealthy && this.kumoConfig.disablePolling) {
+            this.log.info(`Skipping poller for site ${siteId} (streaming healthy, polling disabled)`);
+            return;
+        }
+        const interval = this.isDegradedMode ? this.degradedPollInterval : (this.kumoConfig.pollInterval || 30) * 1000;
+        const intervalSec = interval / 1000;
+        const mode = this.isDegradedMode ? 'DEGRADED' : 'NORMAL';
+        this.log.info(`Starting ${mode} poller for site ${siteId}: ${intervalSec}s intervals`);
+        const accessories = this.accessoryHandlers.filter(handler => handler.getSiteId() === siteId);
+        this.siteAccessories.set(siteId, accessories);
+        this.pollSite(siteId);
+        const timer = setInterval(() => {
+            this.pollSite(siteId);
+        }, interval);
+        this.sitePollers.set(siteId, timer);
+    }
+    async pollSite(siteId) {
+        try {
+            const mode = this.isDegradedMode ? 'DEGRADED' : 'NORMAL';
+            const health = this.isStreamingHealthy ? 'healthy' : 'unhealthy';
+            this.log.debug(`[${mode}] Polling site ${siteId} (streaming: ${health})`);
+            const zones = await this.kumoAPI.getZones(siteId);
+            const accessories = this.siteAccessories.get(siteId) || [];
+            for (const handler of accessories) {
+                const zone = zones.find(z => z.adapter.deviceSerial === handler.getDeviceSerial());
+                if (zone) {
+                    handler.updateFromZone(zone);
+                }
+                else {
+                    this.log.warn(`Zone not found for device: ${handler.getDeviceSerial()}`);
+                }
+            }
+        }
+        catch (error) {
+            this.log.error(`Error polling site ${siteId}:`, error);
+        }
+    }
+    handleStreamingHealthChange(isHealthy) {
+        const wasHealthy = this.isStreamingHealthy;
+        this.isStreamingHealthy = isHealthy;
+        if (wasHealthy && !isHealthy) {
+            this.log.warn('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            this.log.warn('⚠ STREAMING INTERRUPTED');
+            this.log.warn('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            this.enterDegradedMode();
+        }
+        if (!wasHealthy && isHealthy) {
+            this.log.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            this.log.info('✓ STREAMING RESUMED');
+            this.log.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            this.exitDegradedMode();
+        }
+    }
+    enterDegradedMode() {
+        if (this.isDegradedMode) {
+            return;
+        }
+        this.isDegradedMode = true;
+        const intervalSec = this.degradedPollInterval / 1000;
+        this.log.warn(`→ Switching to DEGRADED MODE`);
+        this.log.warn(`→ Polling activated: ${intervalSec}s intervals`);
+        this.log.warn(`→ Updates will continue via API polling`);
+        if (this.kumoConfig.disablePolling) {
+            this.log.warn('→ Overriding disablePolling setting for fallback');
+        }
+        this.restartAllPollers(this.degradedPollInterval);
+    }
+    exitDegradedMode() {
+        if (!this.isDegradedMode) {
+            return;
+        }
+        this.isDegradedMode = false;
+        if (this.kumoConfig.disablePolling) {
+            this.log.info('→ Returning to NORMAL MODE');
+            this.log.info('→ Polling halted (streaming active)');
+            this.log.info('→ Updates resume via real-time streaming');
+            this.stopAllPollers();
+        }
+        else {
+            const normalInterval = (this.kumoConfig.pollInterval || 30) * 1000;
+            const normalSec = normalInterval / 1000;
+            this.log.info('→ Returning to NORMAL MODE');
+            this.log.info(`→ Polling reduced to ${normalSec}s intervals`);
+            this.log.info('→ Primary updates via streaming');
+            this.restartAllPollers(normalInterval);
+        }
+    }
+    restartAllPollers(intervalMs) {
+        const intervalSec = intervalMs / 1000;
+        for (const [siteId, timer] of this.sitePollers) {
+            clearInterval(timer);
+            this.pollSite(siteId);
+            const newTimer = setInterval(() => {
+                this.pollSite(siteId);
+            }, intervalMs);
+            this.sitePollers.set(siteId, newTimer);
+            this.log.debug(`Poller restarted for site ${siteId}: ${intervalSec}s interval`);
+        }
+        const siteCount = this.sitePollers.size;
+        this.log.info(`✓ ${siteCount} site poller(s) active at ${intervalSec}s intervals`);
+    }
+    stopAllPollers() {
+        for (const [siteId, timer] of this.sitePollers) {
+            clearInterval(timer);
+            this.log.debug(`Poller stopped for site ${siteId}`);
+        }
+        this.sitePollers.clear();
+        this.log.info('✓ All polling halted');
+    }
 }
 exports.KumoV3Platform = KumoV3Platform;

package/dist/settings.d.ts

@@ -1,6 +1,7 @@
 export declare const PLATFORM_NAME = "KumoV3";
 export declare const PLUGIN_NAME = "homebridge-mitsubishi-comfort";
 export declare const API_BASE_URL = "https://app-prod.kumocloud.com/v3";
+export declare const SOCKET_BASE_URL = "https://socket-prod.kumocloud.com";
 export declare const TOKEN_REFRESH_INTERVAL: number;
 export declare const POLL_INTERVAL: number;
 export declare const APP_VERSION = "3.2.3";
@@ -10,8 +11,12 @@ export interface KumoConfig {
     username: string;
     password: string;
     pollInterval?: number;
+    disablePolling?: boolean;
     debug?: boolean;
     excludeDevices?: string[];
+    streamingHealthCheckInterval?: number;
+    streamingStaleThreshold?: number;
+    degradedPollInterval?: number;
 }
 export interface LoginResponse {
     id: string;
@@ -71,7 +76,7 @@ export interface DeviceStatus {
 export interface Commands {
     spHeat?: number;
     spCool?: number;
-    operationMode?: 'off' | 'heat' | 'cool' | 'auto';
+    operationMode?: 'off' | 'heat' | 'cool' | 'auto' | 'vent' | 'dry';
     fanSpeed?: 'auto' | 'low' | 'medium' | 'high';
 }
 export interface SendCommandRequest {

package/dist/settings.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APP_VERSION = exports.POLL_INTERVAL = exports.TOKEN_REFRESH_INTERVAL = exports.API_BASE_URL = exports.PLUGIN_NAME = exports.PLATFORM_NAME = void 0;
+exports.APP_VERSION = exports.POLL_INTERVAL = exports.TOKEN_REFRESH_INTERVAL = exports.SOCKET_BASE_URL = exports.API_BASE_URL = exports.PLUGIN_NAME = exports.PLATFORM_NAME = void 0;
 exports.PLATFORM_NAME = 'KumoV3';
 exports.PLUGIN_NAME = 'homebridge-mitsubishi-comfort';
 exports.API_BASE_URL = 'https://app-prod.kumocloud.com/v3';
+exports.SOCKET_BASE_URL = 'https://socket-prod.kumocloud.com';
 exports.TOKEN_REFRESH_INTERVAL = 15 * 60 * 1000;
 exports.POLL_INTERVAL = 30 * 1000;
 exports.APP_VERSION = '3.2.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-mitsubishi-comfort",
-  "version": "1.0.1",
+  "version": "1.3.1",
   "description": "Homebridge plugin for Mitsubishi heat pumps using Kumo Cloud v3 API",
   "author": "burtherman",
   "main": "dist/index.js",
@@ -33,7 +33,8 @@
   },
   "homepage": "https://github.com/burtherman/homebridge-mitsubishi-comfort#readme",
   "dependencies": {
-    "node-fetch": "^3.2.0"
+    "node-fetch": "^3.2.0",
+    "socket.io-client": "^4.8.1"
   },
   "devDependencies": {
     "@types/node": "^15.12.3",