homebridge-mitsubishi-comfort 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# Homebridge Kumo v3 Plugin
+
+A Homebridge plugin for Mitsubishi heat pumps using the Kumo Cloud v3 API.
+
+## Features
+
+- 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
+
+## Installation
+
+### Prerequisites
+
+- Node.js (v14.18.1 or higher)
+- Homebridge (v1.3.5 or higher)
+
+### Install from NPM (once published)
+
+```bash
+npm install -g homebridge-mitsubishi-comfort
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/burtherman/homebridge-mitsubishi-comfort.git
+cd homebridge-mitsubishi-comfort
+npm install
+npm run build
+npm link
+```
+
+## Configuration
+
+Add the following to your Homebridge `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "KumoV3",
+      "name": "Kumo",
+      "username": "your-email@example.com",
+      "password": "your-password"
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `platform` | string | Yes | Must be `KumoV3` |
+| `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 |
+| `debug` | boolean | No | Enable debug logging (default: false) |
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch for Changes
+
+```bash
+npm run watch
+```
+
+This will compile TypeScript, link the plugin, and restart on changes.
+
+## How It Works
+
+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
+
+## Supported Characteristics
+
+- Current Temperature
+- Target Temperature
+- Current Heating/Cooling State
+- Target Heating/Cooling State (Off, Heat, Cool, Auto)
+- Temperature Display Units (Celsius/Fahrenheit)
+- Current Relative Humidity (when available)
+
+## API Endpoints Used
+
+- `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
+
+## Security
+
+### Best Practices
+
+- **Credentials**: Your Kumo Cloud credentials are stored in the Homebridge config file. Ensure this file has appropriate permissions (readable only by the Homebridge user).
+- **Debug Mode**: Only enable debug mode when troubleshooting. Debug logs may contain sensitive information like API endpoints and error details.
+- **Network**: This plugin communicates with Kumo Cloud servers over HTTPS. Ensure your Homebridge instance runs in a secure network environment.
+- **Updates**: Keep the plugin updated to receive security patches.
+
+### What Data is Transmitted
+
+- Authentication credentials (username/password) are sent to Kumo Cloud API during login
+- Device commands and status updates are exchanged with Kumo Cloud servers
+- No data is transmitted to third parties
+- All communication uses HTTPS encryption
+
+## Troubleshooting
+
+### Plugin not discovering devices
+
+- Verify your username and password are correct
+- Check Homebridge logs for authentication errors
+- Ensure your Kumo Cloud account has active devices
+
+### Devices not responding to commands
+
+- Check your internet connection
+- Verify devices are online in the Kumo Cloud app
+- Check Homebridge logs for API errors
+
+### Temperature not updating
+
+- Status is polled every 30 seconds by default
+- Ensure the device is connected (check in Kumo Cloud app)
+- Look for polling errors in Homebridge logs
+
+## License
+
+MIT
+
+## Credits
+
+Based on the Kumo Cloud v3 API and inspired by [homebridge-kumo](https://github.com/fjs21/homebridge-kumo).

package/config.schema.json

@@ -0,0 +1,68 @@
+{
+  "pluginAlias": "KumoV3",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Homebridge plugin for Mitsubishi heat pumps using Kumo Cloud v3 API.",
+  "footerDisplay": "For help and support, visit the [GitHub repository](https://github.com/burtherman/homebridge-mitsubishi-comfort).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Kumo",
+        "required": true
+      },
+      "username": {
+        "title": "Username",
+        "type": "string",
+        "required": true,
+        "format": "email",
+        "description": "Your Kumo Cloud email address"
+      },
+      "password": {
+        "title": "Password",
+        "type": "string",
+        "required": true,
+        "description": "Your Kumo Cloud password"
+      },
+      "pollInterval": {
+        "title": "Poll Interval (seconds)",
+        "type": "integer",
+        "default": 30,
+        "minimum": 5,
+        "description": "How often to poll device status (minimum 5 seconds)"
+      },
+      "debug": {
+        "title": "Debug Mode",
+        "type": "boolean",
+        "default": false,
+        "description": "Enable verbose debug logging (requires running Homebridge with -D flag)"
+      },
+      "excludeDevices": {
+        "title": "Excluded Devices",
+        "type": "array",
+        "items": {
+          "type": "string",
+          "title": "Device Serial Number"
+        },
+        "description": "List of device serial numbers to exclude from HomeKit"
+      }
+    }
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Kumo Cloud Credentials",
+      "expandable": false,
+      "items": ["username", "password"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced Settings",
+      "expandable": true,
+      "expanded": false,
+      "items": ["pollInterval", "excludeDevices", "debug"]
+    }
+  ]
+}

package/dist/accessory.d.ts

@@ -0,0 +1,31 @@
+import { PlatformAccessory, CharacteristicValue } from 'homebridge';
+import { KumoV3Platform } from './platform';
+import { KumoAPI } from './kumo-api';
+export declare class KumoThermostatAccessory {
+    private readonly platform;
+    private readonly accessory;
+    private readonly kumoAPI;
+    private service;
+    private pollTimer;
+    private deviceSerial;
+    private siteId;
+    private currentStatus;
+    private pollIntervalMs;
+    private hasHumiditySensor;
+    constructor(platform: KumoV3Platform, accessory: PlatformAccessory, kumoAPI: KumoAPI, pollIntervalSeconds?: number);
+    private startPolling;
+    private updateStatus;
+    private mapToCurrentHeatingCoolingState;
+    private mapToTargetHeatingCoolingState;
+    private getTargetTempFromStatus;
+    getCurrentHeatingCoolingState(): Promise<CharacteristicValue>;
+    getTargetHeatingCoolingState(): Promise<CharacteristicValue>;
+    setTargetHeatingCoolingState(value: CharacteristicValue): Promise<void>;
+    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

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KumoThermostatAccessory = void 0;
+const settings_1 = require("./settings");
+class KumoThermostatAccessory {
+    constructor(platform, accessory, kumoAPI, pollIntervalSeconds) {
+        this.platform = platform;
+        this.accessory = accessory;
+        this.kumoAPI = kumoAPI;
+        this.pollTimer = null;
+        this.currentStatus = null;
+        this.hasHumiditySensor = false;
+        this.deviceSerial = this.accessory.context.device.deviceSerial;
+        this.siteId = this.accessory.context.device.siteId;
+        this.pollIntervalMs = (pollIntervalSeconds || settings_1.POLL_INTERVAL / 1000) * 1000;
+        this.accessory.getService(this.platform.Service.AccessoryInformation)
+            .setCharacteristic(this.platform.Characteristic.Manufacturer, 'Mitsubishi')
+            .setCharacteristic(this.platform.Characteristic.Model, 'Kumo Cloud Heat Pump')
+            .setCharacteristic(this.platform.Characteristic.SerialNumber, this.deviceSerial);
+        this.service = this.accessory.getService(this.platform.Service.Thermostat) ||
+            this.accessory.addService(this.platform.Service.Thermostat);
+        this.service.setCharacteristic(this.platform.Characteristic.Name, accessory.context.device.displayName);
+        this.service.getCharacteristic(this.platform.Characteristic.CurrentHeatingCoolingState)
+            .onGet(this.getCurrentHeatingCoolingState.bind(this));
+        this.service.getCharacteristic(this.platform.Characteristic.TargetHeatingCoolingState)
+            .onGet(this.getTargetHeatingCoolingState.bind(this))
+            .onSet(this.setTargetHeatingCoolingState.bind(this));
+        this.service.getCharacteristic(this.platform.Characteristic.CurrentTemperature)
+            .onGet(this.getCurrentTemperature.bind(this));
+        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();
+    }
+    startPolling() {
+        this.updateStatus();
+        this.pollTimer = setInterval(() => {
+            this.updateStatus();
+        }, this.pollIntervalMs);
+    }
+    async updateStatus() {
+        try {
+            const result = await this.kumoAPI.getZonesWithETag(this.siteId);
+            if (result.notModified) {
+                this.platform.log.debug(`Status not modified for device ${this.deviceSerial}`);
+                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;
+            }
+            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));
+                return;
+            }
+            const hasHumidity = zone.adapter.humidity !== null && zone.adapter.humidity !== undefined;
+            if (hasHumidity && !this.hasHumiditySensor) {
+                this.hasHumiditySensor = true;
+                this.service.getCharacteristic(this.platform.Characteristic.CurrentRelativeHumidity)
+                    .onGet(this.getCurrentRelativeHumidity.bind(this));
+                this.platform.log.debug(`Added humidity characteristic for device ${this.deviceSerial}`);
+            }
+            else if (!hasHumidity && this.hasHumiditySensor) {
+                this.hasHumiditySensor = false;
+                if (this.service.testCharacteristic(this.platform.Characteristic.CurrentRelativeHumidity)) {
+                    this.service.removeCharacteristic(this.service.getCharacteristic(this.platform.Characteristic.CurrentRelativeHumidity));
+                    this.platform.log.debug(`Removed humidity characteristic for device ${this.deviceSerial}`);
+                }
+            }
+            const status = {
+                id: zone.id,
+                deviceSerial: zone.adapter.deviceSerial,
+                rssi: zone.adapter.rssi || 0,
+                power: zone.adapter.power,
+                operationMode: zone.adapter.operationMode,
+                humidity: zone.adapter.humidity,
+                fanSpeed: zone.adapter.fanSpeed,
+                airDirection: zone.adapter.airDirection,
+                roomTemp: zone.adapter.roomTemp,
+                spCool: zone.adapter.spCool,
+                spHeat: zone.adapter.spHeat,
+                spAuto: zone.adapter.spAuto,
+            };
+            this.currentStatus = status;
+            this.platform.log.debug(`Updated status for ${this.deviceSerial}: roomTemp=${status.roomTemp}, 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)) {
+                this.service.updateCharacteristic(this.platform.Characteristic.CurrentTemperature, status.roomTemp);
+            }
+            const targetTemp = this.getTargetTempFromStatus(status);
+            if (targetTemp !== undefined && targetTemp !== null && !isNaN(targetTemp)) {
+                this.service.updateCharacteristic(this.platform.Characteristic.TargetTemperature, targetTemp);
+            }
+            if (this.hasHumiditySensor && status.humidity !== null) {
+                this.service.updateCharacteristic(this.platform.Characteristic.CurrentRelativeHumidity, status.humidity);
+            }
+        }
+        catch (error) {
+            this.platform.log.error('Error updating device status:', error);
+        }
+    }
+    mapToCurrentHeatingCoolingState(status) {
+        if (status.power === 0) {
+            return this.platform.Characteristic.CurrentHeatingCoolingState.OFF;
+        }
+        switch (status.operationMode) {
+            case 'heat':
+                return this.platform.Characteristic.CurrentHeatingCoolingState.HEAT;
+            case 'cool':
+                return this.platform.Characteristic.CurrentHeatingCoolingState.COOL;
+            case 'auto':
+                const targetTemp = this.getTargetTempFromStatus(status);
+                if (status.roomTemp < targetTemp) {
+                    return this.platform.Characteristic.CurrentHeatingCoolingState.HEAT;
+                }
+                else if (status.roomTemp > targetTemp) {
+                    return this.platform.Characteristic.CurrentHeatingCoolingState.COOL;
+                }
+                return this.platform.Characteristic.CurrentHeatingCoolingState.OFF;
+            case 'off':
+            default:
+                return this.platform.Characteristic.CurrentHeatingCoolingState.OFF;
+        }
+    }
+    mapToTargetHeatingCoolingState(status) {
+        if (status.power === 0 || status.operationMode === 'off') {
+            return this.platform.Characteristic.TargetHeatingCoolingState.OFF;
+        }
+        switch (status.operationMode) {
+            case 'heat':
+                return this.platform.Characteristic.TargetHeatingCoolingState.HEAT;
+            case 'cool':
+                return this.platform.Characteristic.TargetHeatingCoolingState.COOL;
+            case 'auto':
+                return this.platform.Characteristic.TargetHeatingCoolingState.AUTO;
+            default:
+                return this.platform.Characteristic.TargetHeatingCoolingState.OFF;
+        }
+    }
+    getTargetTempFromStatus(status) {
+        if (status.operationMode === 'heat' && status.spHeat !== undefined && status.spHeat !== null) {
+            return status.spHeat;
+        }
+        else if (status.operationMode === 'cool' && status.spCool !== undefined && status.spCool !== null) {
+            return status.spCool;
+        }
+        else if (status.operationMode === 'auto' && status.spAuto !== null && status.spAuto !== undefined) {
+            return status.spAuto;
+        }
+        if (status.spHeat !== undefined && status.spHeat !== null) {
+            return status.spHeat;
+        }
+        return 20;
+    }
+    async getCurrentHeatingCoolingState() {
+        if (!this.currentStatus) {
+            const status = await this.kumoAPI.getDeviceStatus(this.deviceSerial);
+            if (status) {
+                this.currentStatus = status;
+            }
+            else {
+                return this.platform.Characteristic.CurrentHeatingCoolingState.OFF;
+            }
+        }
+        const state = this.mapToCurrentHeatingCoolingState(this.currentStatus);
+        this.platform.log.debug('Get CurrentHeatingCoolingState:', state);
+        return state;
+    }
+    async getTargetHeatingCoolingState() {
+        if (!this.currentStatus) {
+            const status = await this.kumoAPI.getDeviceStatus(this.deviceSerial);
+            if (status) {
+                this.currentStatus = status;
+            }
+            else {
+                return this.platform.Characteristic.TargetHeatingCoolingState.OFF;
+            }
+        }
+        const state = this.mapToTargetHeatingCoolingState(this.currentStatus);
+        this.platform.log.debug('Get TargetHeatingCoolingState:', state);
+        return state;
+    }
+    async setTargetHeatingCoolingState(value) {
+        this.platform.log.debug('Set TargetHeatingCoolingState:', value);
+        let operationMode;
+        switch (value) {
+            case this.platform.Characteristic.TargetHeatingCoolingState.OFF:
+                operationMode = 'off';
+                break;
+            case this.platform.Characteristic.TargetHeatingCoolingState.HEAT:
+                operationMode = 'heat';
+                break;
+            case this.platform.Characteristic.TargetHeatingCoolingState.COOL:
+                operationMode = 'cool';
+                break;
+            case this.platform.Characteristic.TargetHeatingCoolingState.AUTO:
+                operationMode = 'auto';
+                break;
+            default:
+                this.platform.log.error('Unknown target heating cooling state:', value);
+                return;
+        }
+        const success = await this.kumoAPI.sendCommand(this.deviceSerial, {
+            operationMode,
+        });
+        if (success) {
+            setTimeout(() => this.updateStatus(), 1000);
+        }
+        else {
+            this.platform.log.error(`Failed to set target heating cooling state for ${this.accessory.displayName}`);
+        }
+    }
+    async getCurrentTemperature() {
+        if (!this.currentStatus) {
+            const status = await this.kumoAPI.getDeviceStatus(this.deviceSerial);
+            if (status) {
+                this.currentStatus = status;
+            }
+            else {
+                this.platform.log.warn('No status available for getCurrentTemperature');
+                return 20;
+            }
+        }
+        const temp = this.currentStatus.roomTemp;
+        if (temp === undefined || temp === null || isNaN(temp)) {
+            this.platform.log.warn('Invalid roomTemp value:', temp);
+            return 20;
+        }
+        this.platform.log.debug('Get CurrentTemperature:', temp);
+        return temp;
+    }
+    async getTargetTemperature() {
+        if (!this.currentStatus) {
+            const status = await this.kumoAPI.getDeviceStatus(this.deviceSerial);
+            if (status) {
+                this.currentStatus = status;
+            }
+            else {
+                this.platform.log.warn('No status available for getTargetTemperature');
+                return 20;
+            }
+        }
+        const temp = this.getTargetTempFromStatus(this.currentStatus);
+        if (temp === undefined || temp === null || isNaN(temp)) {
+            this.platform.log.warn('Invalid target temperature value:', temp);
+            return 20;
+        }
+        this.platform.log.debug('Get TargetTemperature:', temp);
+        return temp;
+    }
+    async setTargetTemperature(value) {
+        const temp = value;
+        this.platform.log.debug('Set TargetTemperature:', temp);
+        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;
+        }
+        else if (this.currentStatus.operationMode === 'cool') {
+            commands.spCool = roundedTemp;
+        }
+        else if (this.currentStatus.operationMode === 'auto') {
+            commands.spHeat = roundedTemp;
+            commands.spCool = roundedTemp;
+        }
+        else {
+            commands.spHeat = roundedTemp;
+        }
+        const success = await this.kumoAPI.sendCommand(this.deviceSerial, commands);
+        if (success) {
+            setTimeout(() => this.updateStatus(), 1000);
+        }
+        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) {
+            const status = await this.kumoAPI.getDeviceStatus(this.deviceSerial);
+            if (status) {
+                this.currentStatus = status;
+            }
+        }
+        const humidity = ((_a = this.currentStatus) === null || _a === void 0 ? void 0 : _a.humidity) || 0;
+        this.platform.log.debug('Get CurrentRelativeHumidity:', humidity);
+        return humidity;
+    }
+    destroy() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+}
+exports.KumoThermostatAccessory = KumoThermostatAccessory;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+const settings_1 = require("./settings");
+const platform_1 = require("./platform");
+module.exports = (api) => {
+    api.registerPlatform(settings_1.PLATFORM_NAME, platform_1.KumoV3Platform);
+};

package/dist/kumo-api.d.ts

@@ -0,0 +1,30 @@
+import type { Logger } from 'homebridge';
+import { Site, Zone, DeviceStatus, Commands } from './settings';
+export declare class KumoAPI {
+    private readonly username;
+    private readonly password;
+    private readonly log;
+    private accessToken;
+    private refreshToken;
+    private tokenExpiresAt;
+    private refreshTimer;
+    private siteEtags;
+    private debugMode;
+    constructor(username: string, password: string, log: Logger, debug?: boolean);
+    private maskToken;
+    login(): Promise<boolean>;
+    private scheduleTokenRefresh;
+    private refreshAccessToken;
+    private ensureAuthenticated;
+    private getAuthHeaders;
+    private makeAuthenticatedRequest;
+    getSites(): Promise<Site[]>;
+    getZones(siteId: string): Promise<Zone[]>;
+    getZonesWithETag(siteId: string): Promise<{
+        zones: Zone[];
+        notModified: boolean;
+    }>;
+    getDeviceStatus(deviceSerial: string): Promise<DeviceStatus | null>;
+    sendCommand(deviceSerial: string, commands: Commands): Promise<boolean>;
+    destroy(): void;
+}

package/dist/kumo-api.js

@@ -0,0 +1,284 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KumoAPI = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const settings_1 = require("./settings");
+class KumoAPI {
+    constructor(username, password, log, debug = false) {
+        this.username = username;
+        this.password = password;
+        this.log = log;
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.tokenExpiresAt = 0;
+        this.refreshTimer = null;
+        this.siteEtags = new Map();
+        this.debugMode = false;
+        this.debugMode = debug;
+        if (this.debugMode) {
+            this.log.info('Debug mode enabled');
+            this.log.warn('Debug mode may log sensitive information - use only for troubleshooting');
+        }
+    }
+    maskToken(token) {
+        if (!token) {
+            return 'null';
+        }
+        if (token.length <= 8) {
+            return '***';
+        }
+        return `${token.substring(0, 4)}...${token.substring(token.length - 4)}`;
+    }
+    async login() {
+        try {
+            this.log.debug('Attempting to login to Kumo Cloud API');
+            const response = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}/login`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                    'X-App-Version': settings_1.APP_VERSION,
+                },
+                body: JSON.stringify({
+                    username: this.username,
+                    password: this.password,
+                    appVersion: settings_1.APP_VERSION,
+                }),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                this.log.error(`Login failed with status: ${response.status}`);
+                if (this.debugMode && errorText) {
+                    this.log.debug(`Login error response: ${errorText}`);
+                }
+                return false;
+            }
+            const data = await response.json();
+            this.accessToken = data.token.access;
+            this.refreshToken = data.token.refresh;
+            this.tokenExpiresAt = Date.now() + settings_1.TOKEN_REFRESH_INTERVAL;
+            this.log.info('Successfully logged in to Kumo Cloud API');
+            this.scheduleTokenRefresh();
+            return true;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.log.error('Login error:', error.message);
+                if (this.debugMode) {
+                    this.log.debug('Login error stack:', error.stack);
+                }
+            }
+            else {
+                this.log.error('Login error: Unknown error occurred');
+            }
+            return false;
+        }
+    }
+    scheduleTokenRefresh() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+        }
+        const refreshIn = settings_1.TOKEN_REFRESH_INTERVAL - (5 * 60 * 1000);
+        this.refreshTimer = setTimeout(async () => {
+            this.log.debug('Refreshing access token');
+            await this.refreshAccessToken();
+        }, refreshIn);
+    }
+    async refreshAccessToken() {
+        if (!this.refreshToken) {
+            this.log.error('No refresh token available, need to login again');
+            return await this.login();
+        }
+        try {
+            this.log.debug('Refreshing access token');
+            const response = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}/refresh`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Accept': 'application/json',
+                    'Authorization': `Bearer ${this.refreshToken}`,
+                    'X-App-Version': settings_1.APP_VERSION,
+                },
+            });
+            if (!response.ok) {
+                this.log.warn('Token refresh failed, attempting full login');
+                return await this.login();
+            }
+            const data = await response.json();
+            this.accessToken = data.token.access;
+            this.refreshToken = data.token.refresh;
+            this.tokenExpiresAt = Date.now() + settings_1.TOKEN_REFRESH_INTERVAL;
+            this.log.debug('Access token refreshed successfully');
+            this.scheduleTokenRefresh();
+            return true;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.log.error('Token refresh error:', error.message);
+            }
+            else {
+                this.log.error('Token refresh error: Unknown error occurred');
+            }
+            return await this.login();
+        }
+    }
+    async ensureAuthenticated() {
+        if (!this.accessToken || Date.now() >= this.tokenExpiresAt - (5 * 60 * 1000)) {
+            if (!this.refreshToken) {
+                return await this.login();
+            }
+            return await this.refreshAccessToken();
+        }
+        return true;
+    }
+    getAuthHeaders() {
+        return {
+            'Authorization': `Bearer ${this.accessToken}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'X-App-Version': settings_1.APP_VERSION,
+        };
+    }
+    async makeAuthenticatedRequest(endpoint, method = 'GET', body) {
+        const authenticated = await this.ensureAuthenticated();
+        if (!authenticated) {
+            this.log.error('Failed to authenticate');
+            return null;
+        }
+        try {
+            const options = {
+                method,
+                headers: this.getAuthHeaders(),
+            };
+            if (body) {
+                options.body = JSON.stringify(body);
+            }
+            const response = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}${endpoint}`, options);
+            if (response.status === 401) {
+                this.log.debug('Received 401, refreshing token and retrying');
+                const refreshed = await this.refreshAccessToken();
+                if (!refreshed) {
+                    return null;
+                }
+                options.headers = this.getAuthHeaders();
+                const retryResponse = await (0, node_fetch_1.default)(`${settings_1.API_BASE_URL}${endpoint}`, options);
+                if (!retryResponse.ok) {
+                    this.log.error(`Request failed after retry: ${retryResponse.status}`);
+                    return null;
+                }
+                return await retryResponse.json();
+            }
+            if (!response.ok) {
+                this.log.error(`Request failed with status: ${response.status}`);
+                return null;
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.log.error('Request error:', error.message);
+                if (this.debugMode) {
+                    this.log.debug('Full error stack:', error.stack);
+                }
+            }
+            else {
+                this.log.error('Request error: Unknown error occurred');
+            }
+            return null;
+        }
+    }
+    async getSites() {
+        this.log.debug('Fetching sites');
+        const sites = await this.makeAuthenticatedRequest('/sites');
+        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) {
+        const etag = this.siteEtags.get(siteId);
+        const authenticated = await this.ensureAuthenticated();
+        if (!authenticated) {
+            this.log.error('Failed to authenticate');
+            return { zones: [], notModified: false };
+        }
+        try {
+            const headers = this.getAuthHeaders();
+            if (etag) {
+                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 };
+            }
+            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);
+            }
+            const zones = await response.json();
+            if (this.debugMode) {
+                this.log.debug(`Fetched ${zones.length} zones for site ${siteId}`);
+                zones.forEach(zone => {
+                    this.log.debug(`Zone ${zone.name} (${zone.adapter.deviceSerial}): roomTemp=${zone.adapter.roomTemp}`);
+                });
+            }
+            return { zones, notModified: false };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.log.error('Error fetching zones with ETag:', error.message);
+            }
+            else {
+                this.log.error('Error fetching zones: Unknown error occurred');
+            }
+            return { zones: [], notModified: false };
+        }
+    }
+    async getDeviceStatus(deviceSerial) {
+        this.log.debug(`Fetching status for device: ${deviceSerial}`);
+        return await this.makeAuthenticatedRequest(`/devices/${deviceSerial}/status`);
+    }
+    async sendCommand(deviceSerial, commands) {
+        this.log.debug(`Sending command to device ${deviceSerial}:`, JSON.stringify(commands));
+        const request = {
+            deviceSerial,
+            commands,
+        };
+        const response = await this.makeAuthenticatedRequest('/devices/send-command', 'POST', request);
+        if (!response) {
+            this.log.error(`Send command failed: no response from API for device ${deviceSerial}`);
+            return false;
+        }
+        if (!response.devices || !Array.isArray(response.devices)) {
+            this.log.error(`Send command failed: unexpected response format for device ${deviceSerial}`);
+            if (this.debugMode) {
+                this.log.debug(`Response:`, JSON.stringify(response));
+            }
+            return false;
+        }
+        if (!response.devices.includes(deviceSerial)) {
+            this.log.error(`Send command failed: device ${deviceSerial} not in response devices list`);
+            return false;
+        }
+        this.log.debug(`Command sent successfully to device ${deviceSerial}`);
+        return true;
+    }
+    destroy() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+}
+exports.KumoAPI = KumoAPI;

package/dist/platform.d.ts

@@ -0,0 +1,16 @@
+import { API, DynamicPlatformPlugin, Logger, PlatformAccessory, PlatformConfig, Service, Characteristic } from 'homebridge';
+export declare class KumoV3Platform implements DynamicPlatformPlugin {
+    readonly log: Logger;
+    readonly config: PlatformConfig;
+    readonly api: API;
+    readonly Service: typeof Service;
+    readonly Characteristic: typeof Characteristic;
+    readonly accessories: PlatformAccessory[];
+    private readonly accessoryHandlers;
+    private readonly kumoAPI;
+    private readonly kumoConfig;
+    constructor(log: Logger, config: PlatformConfig, api: API);
+    private cleanup;
+    configureAccessory(accessory: PlatformAccessory): void;
+    discoverDevices(): Promise<void>;
+}

package/dist/platform.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KumoV3Platform = void 0;
+const settings_1 = require("./settings");
+const kumo_api_1 = require("./kumo-api");
+const accessory_1 = require("./accessory");
+class KumoV3Platform {
+    constructor(log, config, api) {
+        this.log = log;
+        this.config = config;
+        this.api = api;
+        this.Service = this.api.hap.Service;
+        this.Characteristic = this.api.hap.Characteristic;
+        this.accessories = [];
+        this.accessoryHandlers = [];
+        this.kumoConfig = config;
+        this.log.debug('Initializing platform:', this.config.name);
+        const kumoConfig = this.kumoConfig;
+        if (!kumoConfig.username || !kumoConfig.password) {
+            this.log.error('Username and password are required in config');
+            throw new Error('Missing required configuration');
+        }
+        if (typeof kumoConfig.username !== 'string' || !kumoConfig.username.includes('@')) {
+            this.log.error('Username must be a valid email address');
+            throw new Error('Invalid username format');
+        }
+        if (typeof kumoConfig.password !== 'string' || kumoConfig.password.trim().length === 0) {
+            this.log.error('Password must be a non-empty string');
+            throw new Error('Invalid password format');
+        }
+        if (kumoConfig.pollInterval !== undefined) {
+            if (typeof kumoConfig.pollInterval !== 'number' || kumoConfig.pollInterval < 5) {
+                this.log.error('Poll interval must be a number >= 5 seconds');
+                throw new Error('Invalid poll interval');
+            }
+        }
+        this.kumoAPI = new kumo_api_1.KumoAPI(kumoConfig.username, kumoConfig.password, this.log, kumoConfig.debug || false);
+        this.api.on('didFinishLaunching', () => {
+            log.debug('Executed didFinishLaunching callback');
+            this.discoverDevices();
+        });
+        this.api.on('shutdown', () => {
+            log.debug('Shutting down platform');
+            this.cleanup();
+        });
+    }
+    cleanup() {
+        for (const handler of this.accessoryHandlers) {
+            handler.destroy();
+        }
+        this.accessoryHandlers.length = 0;
+        this.kumoAPI.destroy();
+    }
+    configureAccessory(accessory) {
+        this.log.info('Loading accessory from cache:', accessory.displayName);
+        this.accessories.push(accessory);
+    }
+    async discoverDevices() {
+        var _a;
+        try {
+            this.log.info('Starting device discovery');
+            const loginSuccess = await this.kumoAPI.login();
+            if (!loginSuccess) {
+                this.log.error('Failed to login to Kumo Cloud API');
+                return;
+            }
+            const sites = await this.kumoAPI.getSites();
+            if (sites.length === 0) {
+                this.log.warn('No sites found');
+                return;
+            }
+            this.log.info(`Found ${sites.length} site(s)`);
+            const discoveredDevices = [];
+            for (const site of sites) {
+                this.log.debug(`Fetching zones for site: ${site.name}`);
+                const zones = await this.kumoAPI.getZones(site.id);
+                for (const zone of zones) {
+                    if (!zone.isActive) {
+                        this.log.debug(`Skipping inactive zone: ${zone.name}`);
+                        continue;
+                    }
+                    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})`);
+                        continue;
+                    }
+                    const uuid = this.api.hap.uuid.generate(deviceSerial);
+                    discoveredDevices.push({
+                        uuid,
+                        displayName,
+                        deviceSerial,
+                        zoneName: zone.name,
+                    });
+                    this.log.info(`Discovered device: ${displayName} (${deviceSerial})`);
+                    const existingAccessory = this.accessories.find(accessory => accessory.UUID === uuid);
+                    if (existingAccessory) {
+                        this.log.info('Restoring existing accessory from cache:', existingAccessory.displayName);
+                        existingAccessory.context.device = {
+                            deviceSerial,
+                            zoneName: zone.name,
+                            displayName,
+                            siteId: site.id,
+                        };
+                        const handler = new accessory_1.KumoThermostatAccessory(this, existingAccessory, this.kumoAPI, this.kumoConfig.pollInterval);
+                        this.accessoryHandlers.push(handler);
+                        this.api.updatePlatformAccessories([existingAccessory]);
+                    }
+                    else {
+                        this.log.info('Adding new accessory:', displayName);
+                        const accessory = new this.api.platformAccessory(displayName, uuid);
+                        accessory.context.device = {
+                            deviceSerial,
+                            zoneName: zone.name,
+                            displayName,
+                            siteId: site.id,
+                        };
+                        const handler = new accessory_1.KumoThermostatAccessory(this, accessory, this.kumoAPI, this.kumoConfig.pollInterval);
+                        this.accessoryHandlers.push(handler);
+                        this.api.registerPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, [accessory]);
+                        this.accessories.push(accessory);
+                    }
+                }
+            }
+            const staleAccessories = this.accessories.filter(accessory => !discoveredDevices.find(device => device.uuid === accessory.UUID));
+            if (staleAccessories.length > 0) {
+                this.log.info(`Removing ${staleAccessories.length} stale accessory(ies)`);
+                this.api.unregisterPlatformAccessories(settings_1.PLUGIN_NAME, settings_1.PLATFORM_NAME, staleAccessories);
+            }
+            this.log.info('Device discovery completed');
+        }
+        catch (error) {
+            this.log.error('Error during device discovery:', error);
+        }
+    }
+}
+exports.KumoV3Platform = KumoV3Platform;

package/dist/settings.d.ts

@@ -0,0 +1,83 @@
+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 TOKEN_REFRESH_INTERVAL: number;
+export declare const POLL_INTERVAL: number;
+export declare const APP_VERSION = "3.2.3";
+export interface KumoConfig {
+    platform: string;
+    name?: string;
+    username: string;
+    password: string;
+    pollInterval?: number;
+    debug?: boolean;
+    excludeDevices?: string[];
+}
+export interface LoginResponse {
+    id: string;
+    username: string;
+    email: string;
+    token: {
+        access: string;
+        refresh: string;
+    };
+    preferences?: Record<string, unknown>;
+}
+export interface Site {
+    id: string;
+    name: string;
+}
+export interface Zone {
+    id: string;
+    name: string;
+    isActive: boolean;
+    adapter: Adapter;
+}
+export interface Adapter {
+    id: string;
+    deviceSerial: string;
+    roomTemp: number;
+    spHeat: number;
+    spCool: number;
+    spAuto: number | null;
+    humidity: number | null;
+    power: number;
+    operationMode: string;
+    previousOperationMode: string;
+    fanSpeed: string;
+    airDirection: string;
+    connected: boolean;
+    isSimulator: boolean;
+    hasSensor: boolean;
+    hasMhk2: boolean;
+    scheduleOwner: string;
+    scheduleHoldEndTime: number;
+    rssi?: number;
+}
+export interface DeviceStatus {
+    id: string;
+    deviceSerial: string;
+    rssi: number;
+    power: number;
+    operationMode: string;
+    humidity: number | null;
+    fanSpeed: string;
+    airDirection: string;
+    roomTemp: number;
+    spCool: number;
+    spHeat: number;
+    spAuto: number | null;
+}
+export interface Commands {
+    spHeat?: number;
+    spCool?: number;
+    operationMode?: 'off' | 'heat' | 'cool' | 'auto';
+    fanSpeed?: 'auto' | 'low' | 'medium' | 'high';
+}
+export interface SendCommandRequest {
+    deviceSerial: string;
+    commands: Commands;
+}
+export interface SendCommandResponse {
+    devices: string[];
+}

package/dist/settings.js

@@ -0,0 +1,9 @@
+"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.PLATFORM_NAME = 'KumoV3';
+exports.PLUGIN_NAME = 'homebridge-mitsubishi-comfort';
+exports.API_BASE_URL = 'https://app-prod.kumocloud.com/v3';
+exports.TOKEN_REFRESH_INTERVAL = 15 * 60 * 1000;
+exports.POLL_INTERVAL = 30 * 1000;
+exports.APP_VERSION = '3.2.3';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "homebridge-mitsubishi-comfort",
+  "version": "1.0.0",
+  "description": "Homebridge plugin for Mitsubishi heat pumps using Kumo Cloud v3 API",
+  "author": "burtherman",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "config.schema.json"
+  ],
+  "scripts": {
+    "build": "rimraf ./dist && tsc",
+    "watch": "npm run build && npm link && nodemon",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "keywords": [
+    "homebridge-plugin",
+    "mitsubishi",
+    "kumo",
+    "heat-pump"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": "^1.6.0 || ^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/burtherman/homebridge-mitsubishi-comfort.git"
+  },
+  "bugs": {
+    "url": "https://github.com/burtherman/homebridge-mitsubishi-comfort/issues"
+  },
+  "homepage": "https://github.com/burtherman/homebridge-mitsubishi-comfort#readme",
+  "dependencies": {
+    "node-fetch": "^3.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^15.12.3",
+    "homebridge": "^1.3.1",
+    "nodemon": "^2.0.7",
+    "rimraf": "^3.0.2",
+    "typescript": "^4.2.2"
+  }
+}