homebridge-viessmann-vicare 2.0.69 → 2.0.71

package/README.md

@@ -1033,6 +1033,11 @@ For issues and questions:
 
 ## 📈 Changelog
 
+### [2.0.70] - 2026-05-29
+- feat: TRV / Room Sensor discovery mode (`features.enableRoomSensorDiscovery`) — scans all gateway devices, logs every API feature path+value tagged `[RoomDiscovery]`, creates a provisional HomeKit `TemperatureSensor` for each device with a temperature reading
+- feat: report generation timeout now configurable (`reportServerTimeout`, default 300 s, range 60–1800 s) — exposed in Homebridge Config UI X
+- fix: report server `--timeout` arg forwarded from plugin config to child process
+
 ### [2.0.68] - 2026-05-29
 - fix: report server now logs actual LAN IP (`http://192.168.x.x:PORT`) instead of `localhost`/`0.0.0.0` — URL is reachable from any device on the network
 - fix: report generation timeout raised from 60 s to 300 s — fixes timeout error with large CSV files (90+ days, 26 000+ rows)

package/SETUP-GUIDE.md

@@ -1,8 +1,8 @@
-# Complete Setup Guide - v2.0.68
+# Complete Setup Guide - v2.0.70
 
 ## Overview
 
-This guide will walk you through setting up the Viessmann ViCare plugin v2.0.68 for Homebridge, including all the advanced features like intelligent caching, rate limiting protection, comprehensive configuration options, **complete localization support with custom names**, **CSV history logging**, **HTML diagnostic reports**, **energy system monitoring** (PV, battery, wallbox), and **heating schedule awareness** with visual bands in the HTML report, and **heat pump (Wärmepumpe) support** with automatic device detection.
+This guide will walk you through setting up the Viessmann ViCare plugin v2.0.70 for Homebridge, including all the advanced features like intelligent caching, rate limiting protection, comprehensive configuration options, **complete localization support with custom names**, **CSV history logging**, **HTML diagnostic reports**, **energy system monitoring** (PV, battery, wallbox), and **heating schedule awareness** with visual bands in the HTML report, and **heat pump (Wärmepumpe) support** with automatic device detection.
 
 ## Prerequisites
 
@@ -1228,6 +1228,11 @@ sudo systemctl restart homebridge
 
 ## Changelog
 
+### v2.0.70 (2026-05-29)
+- feat: TRV/room sensor discovery mode (enableRoomSensorDiscovery flag)
+- feat: report generation timeout configurable (reportServerTimeout, 60–1800 s)
+- fix: --timeout forwarded from plugin config to report server process
+
 ### v2.0.68 (2026-05-29)
 - fix: report server now logs actual LAN IP instead of localhost/0.0.0.0
 - fix: report generation timeout raised from 60 s to 300 s (fixes error with 90+ day CSV)

package/config.schema.json

@@ -433,6 +433,12 @@
             "type": "boolean",
             "default": true,
             "description": "Create separate accessories showing burner status, modulation level, and statistics."
+          },
+          "enableRoomSensorDiscovery": {
+            "title": "Enable Room Sensor Discovery (TRV / Smart Climate)",
+            "type": "boolean",
+            "default": false,
+            "description": "Scan all gateway devices for thermostatic radiator valves (TRVs) or per-room temperature sensors. Creates a HomeKit TemperatureSensor for each discovered device and dumps all API feature paths to the Homebridge log. Enable this if you have Viessmann ViCare Smart Climate and want to help implement full TRV support. Disable in production — generates verbose logs."
           }
         }
       },
@@ -510,6 +516,14 @@
             "description": "Duration in ms to block regular polling from overwriting command state after a command is sent. Default: 120000 (2 minutes)."
           }
         }
+      },
+      "reportServerTimeout": {
+        "title": "Report Server Generation Timeout",
+        "type": "integer",
+        "default": 600,
+        "minimum": 120,
+        "maximum": 3600,
+        "description": "Maximum time in seconds for report generation. RPi 3 benchmark: ~365s for 90 days / ~1460s for 365 days. Default: 600s. Range: 120–3600s."
       }
     },
     "required": [

package/dist/accessories/room-sensor-accessory.d.ts

@@ -0,0 +1,72 @@
+/**
+ * ViessmannRoomSensorAccessory
+ *
+ * DISCOVERY / DIAGNOSTIC STUB — v2.0.69
+ *
+ * Enabled via: features.enableRoomSensorDiscovery = true
+ *
+ * Purpose:
+ *   Users with Viessmann ViCare Smart Climate thermostatic radiator valves (TRVs)
+ *   or per-room temperature sensors can enable this mode to:
+ *     1. Log ALL feature paths of every non-main device in the gateway.
+ *     2. Create a HomeKit TemperatureSensor accessory for every device that
+ *        exposes at least one numeric temperature value.
+ *
+ * What this solves:
+ *   The exact API feature paths for TRVs vary by model/generation. By running
+ *   this discovery mode and sharing the Homebridge logs, users provide the data
+ *   needed to implement full per-room control in a future release.
+ *
+ * How to use:
+ *   1. Set features.enableRoomSensorDiscovery: true in plugin config.
+ *   2. Restart Homebridge.
+ *   3. Check logs for lines starting with "[RoomDiscovery]".
+ *   4. Share the log output in a GitHub issue — it contains all feature paths
+ *      and property values for your TRV devices.
+ *
+ * HomeKit accessories created:
+ *   - One TemperatureSensor per discovered device with a temperature reading.
+ *   - Name: "<InstallationPrefix> Room <modelId|deviceId>"
+ *   - The sensor shows the best available temperature (room > supply > general).
+ *
+ * This file will be replaced by a full implementation once the API paths
+ * are known for common TRV models (Viessmann ViCare Smart Thermostat, etc.).
+ */
+import { PlatformAccessory } from 'homebridge';
+import { ViessmannPlatform } from '../platform';
+import { ViessmannFeature, ViessmannDevice, ViessmannInstallation, ViessmannGateway } from '../viessmann-api-endpoints';
+export interface RoomSensorDiscoveryResult {
+    device: ViessmannDevice;
+    tempFeaturePath?: string;
+    tempPropName?: string;
+    tempLabel?: string;
+    currentTemp?: number;
+    allTempFeatures: Array<{
+        path: string;
+        prop: string;
+        value: number;
+        unit: string;
+    }>;
+    allFeatureCount: number;
+    matchedRole?: string;
+}
+/**
+ * Scan a device's features and return structured discovery data.
+ * Also dumps a detailed log to help reverse-engineer unknown TRV models.
+ */
+export declare function discoverRoomSensorData(platform: ViessmannPlatform, device: ViessmannDevice, features: ViessmannFeature[]): RoomSensorDiscoveryResult;
+export declare class ViessmannRoomSensorAccessory {
+    private readonly platform;
+    private readonly accessory;
+    private readonly installation;
+    private readonly gateway;
+    private temperatureService;
+    private readonly TAG;
+    private discoveryResult;
+    constructor(platform: ViessmannPlatform, accessory: PlatformAccessory, installation: ViessmannInstallation, gateway: ViessmannGateway, device: ViessmannDevice, features: ViessmannFeature[]);
+    /**
+     * Called by the platform update loop at each refresh cycle.
+     */
+    update(features: ViessmannFeature[]): void;
+}
+//# sourceMappingURL=room-sensor-accessory.d.ts.map

package/dist/accessories/room-sensor-accessory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-sensor-accessory.d.ts","sourceRoot":"","sources":["../../src/accessories/room-sensor-accessory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,iBAAiB,EAAW,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAiCxH,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,eAAe,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpF,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,yBAAyB,CAsG3B;AAID,qBAAa,4BAA4B;IAQrC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,kBAAkB,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IAGtC,OAAO,CAAC,eAAe,CAA4B;gBAGhC,QAAQ,EAAE,iBAAiB,EAC3B,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,qBAAqB,EACnC,OAAO,EAAE,gBAAgB,EAC1C,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,gBAAgB,EAAE;IA2C9B;;OAEG;IACI,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI;CA2BlD"}

package/dist/accessories/room-sensor-accessory.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * ViessmannRoomSensorAccessory
+ *
+ * DISCOVERY / DIAGNOSTIC STUB — v2.0.69
+ *
+ * Enabled via: features.enableRoomSensorDiscovery = true
+ *
+ * Purpose:
+ *   Users with Viessmann ViCare Smart Climate thermostatic radiator valves (TRVs)
+ *   or per-room temperature sensors can enable this mode to:
+ *     1. Log ALL feature paths of every non-main device in the gateway.
+ *     2. Create a HomeKit TemperatureSensor accessory for every device that
+ *        exposes at least one numeric temperature value.
+ *
+ * What this solves:
+ *   The exact API feature paths for TRVs vary by model/generation. By running
+ *   this discovery mode and sharing the Homebridge logs, users provide the data
+ *   needed to implement full per-room control in a future release.
+ *
+ * How to use:
+ *   1. Set features.enableRoomSensorDiscovery: true in plugin config.
+ *   2. Restart Homebridge.
+ *   3. Check logs for lines starting with "[RoomDiscovery]".
+ *   4. Share the log output in a GitHub issue — it contains all feature paths
+ *      and property values for your TRV devices.
+ *
+ * HomeKit accessories created:
+ *   - One TemperatureSensor per discovered device with a temperature reading.
+ *   - Name: "<InstallationPrefix> Room <modelId|deviceId>"
+ *   - The sensor shows the best available temperature (room > supply > general).
+ *
+ * This file will be replaced by a full implementation once the API paths
+ * are known for common TRV models (Viessmann ViCare Smart Thermostat, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViessmannRoomSensorAccessory = void 0;
+exports.discoverRoomSensorData = discoverRoomSensorData;
+// ── Candidate feature paths for room/zone temperature, in priority order ──────
+// Extend this list as new devices are discovered.
+const TEMP_PATH_CANDIDATES = [
+    // Zone-based (ViCare Smart Climate typical)
+    { path: 'heating.zones.0.sensors.temperature.room', prop: 'value', label: 'zone0.room' },
+    { path: 'heating.zones.1.sensors.temperature.room', prop: 'value', label: 'zone1.room' },
+    { path: 'heating.zones.2.sensors.temperature.room', prop: 'value', label: 'zone2.room' },
+    { path: 'heating.zones.3.sensors.temperature.room', prop: 'value', label: 'zone3.room' },
+    // Circuit-based (standard HC)
+    { path: 'heating.circuits.0.sensors.temperature.room', prop: 'value', label: 'hc0.room' },
+    { path: 'heating.circuits.1.sensors.temperature.room', prop: 'value', label: 'hc1.room' },
+    // Generic device-level temperature (TRV models)
+    { path: 'temperature.current', prop: 'value', label: 'temp.current' },
+    { path: 'temperature.value', prop: 'value', label: 'temp.value' },
+    { path: 'temperature.basic', prop: 'value', label: 'temp.basic' },
+    // Setpoint (secondary interest)
+    { path: 'temperature.setpoint', prop: 'value', label: 'temp.setpoint' },
+    { path: 'heating.zones.0.temperature.setpoint', prop: 'value', label: 'zone0.setpoint' },
+];
+// Valve/TRV-specific feature paths we want to capture but not display
+const VALVE_PATH_PATTERNS = ['valve', 'opening', 'position', 'level'];
+// Roles that indicate a TRV or room sensor device
+const ROOM_DEVICE_ROLES = [
+    'room', 'remote-control', 'remote', 'sensor',
+    'valve', 'thermostat', 'zone',
+];
+/**
+ * Scan a device's features and return structured discovery data.
+ * Also dumps a detailed log to help reverse-engineer unknown TRV models.
+ */
+function discoverRoomSensorData(platform, device, features) {
+    const log = platform.log;
+    const TAG = '[RoomDiscovery]';
+    const roles = device.roles ?? [];
+    const modelId = device.modelId || device.id;
+    const matchedRole = roles.find(r => ROOM_DEVICE_ROLES.some(k => r.toLowerCase().includes(k)));
+    log.info(`${TAG} ──────────────────────────────────────────────`);
+    log.info(`${TAG} Device id=${device.id} model=${modelId}`);
+    log.info(`${TAG}   deviceType: ${device.deviceType}`);
+    log.info(`${TAG}   roles: [${roles.join(', ')}]`);
+    log.info(`${TAG}   status: ${device.status}`);
+    log.info(`${TAG}   matched role: ${matchedRole ?? '(none — showing all features anyway)'}`);
+    log.info(`${TAG}   total features: ${features.length}`);
+    log.info(`${TAG} ── Enabled features with properties ──────────`);
+    const allTempFeatures = [];
+    // Log ALL enabled features — this is the diagnostic payload
+    for (const f of features.filter(x => x.isEnabled)) {
+        const props = f.properties ?? {};
+        const cmds = Object.keys(f.commands ?? {});
+        const pKeys = Object.keys(props);
+        log.info(`${TAG}   [${f.isEnabled ? '✓' : '✗'}] ${f.feature}`);
+        for (const pk of pKeys) {
+            const p = props[pk];
+            const val = p?.value;
+            const unit = p?.unit ?? '';
+            const type = p?.type ?? typeof val;
+            if (val !== undefined && val !== null) {
+                // Collect numeric temperature-range values
+                if (typeof val === 'number' && val > -30 && val < 100 && unit !== '%') {
+                    allTempFeatures.push({ path: f.feature, prop: pk, value: val, unit });
+                }
+                const display = Array.isArray(val)
+                    ? `[${val.slice(0, 4).join(', ')}${val.length > 4 ? '…' : ''}]`
+                    : String(val);
+                log.info(`${TAG}     ${pk}: ${display} ${unit} (type:${type})`);
+            }
+        }
+        if (cmds.length > 0) {
+            log.info(`${TAG}     commands: ${cmds.join(', ')}`);
+        }
+    }
+    // Try to match a known temperature path
+    let bestPath;
+    let bestProp;
+    let bestLabel;
+    let bestValue;
+    const featureMap = new Map(features.map(f => [f.feature, f]));
+    for (const candidate of TEMP_PATH_CANDIDATES) {
+        const feat = featureMap.get(candidate.path);
+        if (feat?.isEnabled) {
+            const val = feat.properties?.[candidate.prop]?.value;
+            if (typeof val === 'number' && val > -30 && val < 100) {
+                bestPath = candidate.path;
+                bestProp = candidate.prop;
+                bestLabel = candidate.label;
+                bestValue = val;
+                log.info(`${TAG}   → MATCH: ${candidate.path}.${candidate.prop} = ${val}°C [${candidate.label}]`);
+                break;
+            }
+        }
+    }
+    // Fallback: use first discovered temp feature in range
+    if (!bestPath && allTempFeatures.length > 0) {
+        const fb = allTempFeatures[0];
+        bestPath = fb.path;
+        bestProp = fb.prop;
+        bestLabel = 'auto-detected';
+        bestValue = fb.value;
+        log.info(`${TAG}   → FALLBACK: ${fb.path}.${fb.prop} = ${fb.value}${fb.unit}`);
+    }
+    if (!bestPath) {
+        log.info(`${TAG}   → No temperature feature found for device ${device.id}`);
+        log.info(`${TAG}   ℹ️ Share these logs in a GitHub issue to help implement full TRV support`);
+    }
+    log.info(`${TAG} ──────────────────────────────────────────────`);
+    return {
+        device,
+        tempFeaturePath: bestPath,
+        tempPropName: bestProp,
+        tempLabel: bestLabel,
+        currentTemp: bestValue,
+        allTempFeatures,
+        allFeatureCount: features.length,
+        matchedRole,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+class ViessmannRoomSensorAccessory {
+    platform;
+    accessory;
+    installation;
+    gateway;
+    temperatureService;
+    TAG = '[RoomSensor]';
+    // Discovery result: saved at init, updated at each refresh
+    discoveryResult;
+    constructor(platform, accessory, installation, gateway, device, features) {
+        this.platform = platform;
+        this.accessory = accessory;
+        this.installation = installation;
+        this.gateway = gateway;
+        const { Service: Svc, Characteristic: Char } = platform;
+        // Run discovery scan
+        this.discoveryResult = discoverRoomSensorData(platform, device, features);
+        // AccessoryInformation
+        accessory.getService(Svc.AccessoryInformation)
+            .setCharacteristic(Char.Manufacturer, 'Viessmann')
+            .setCharacteristic(Char.Model, device.modelId || 'Room Sensor (Discovery)')
+            .setCharacteristic(Char.SerialNumber, `${installation.id}-${device.id}`);
+        // TemperatureSensor service
+        this.temperatureService =
+            accessory.getService(Svc.TemperatureSensor) ||
+                accessory.addService(Svc.TemperatureSensor, accessory.displayName);
+        // Initial value
+        const initTemp = this.discoveryResult.currentTemp ?? 20;
+        this.temperatureService
+            .getCharacteristic(Char.CurrentTemperature)
+            .updateValue(initTemp);
+        // StatusActive: true if we found a temperature path
+        this.temperatureService
+            .getCharacteristic(Char.StatusActive)
+            .updateValue(!!this.discoveryResult.tempFeaturePath);
+        if (this.discoveryResult.tempFeaturePath) {
+            platform.log.info(`${this.TAG} "${accessory.displayName}" — ` +
+                `reading ${this.discoveryResult.tempLabel} (${this.discoveryResult.tempFeaturePath}) ` +
+                `= ${initTemp}°C`);
+        }
+        else {
+            platform.log.warn(`${this.TAG} "${accessory.displayName}" — no temperature feature found. ` +
+                `Check logs for full feature list and open a GitHub issue.`);
+        }
+    }
+    /**
+     * Called by the platform update loop at each refresh cycle.
+     */
+    update(features) {
+        const { Characteristic: Char } = this.platform;
+        const { tempFeaturePath, tempPropName } = this.discoveryResult;
+        if (!tempFeaturePath || !tempPropName) {
+            this.platform.log.debug(`${this.TAG} "${this.accessory.displayName}" — no path, skipping update`);
+            return;
+        }
+        const feat = features.find(f => f.feature === tempFeaturePath);
+        if (!feat?.isEnabled) {
+            this.platform.log.debug(`${this.TAG} "${this.accessory.displayName}" — feature not found/enabled`);
+            this.temperatureService.getCharacteristic(Char.StatusActive).updateValue(false);
+            return;
+        }
+        const raw = feat.properties?.[tempPropName]?.value;
+        if (typeof raw !== 'number') {
+            this.platform.log.debug(`${this.TAG} "${this.accessory.displayName}" — non-numeric value: ${raw}`);
+            return;
+        }
+        const temp = Math.max(-270, Math.min(100, raw));
+        this.temperatureService.getCharacteristic(Char.CurrentTemperature).updateValue(temp);
+        this.temperatureService.getCharacteristic(Char.StatusActive).updateValue(true);
+        this.platform.log.debug(`${this.TAG} "${this.accessory.displayName}" — temp: ${temp}°C [${this.discoveryResult.tempLabel}]`);
+    }
+}
+exports.ViessmannRoomSensorAccessory = ViessmannRoomSensorAccessory;

package/dist/platform.d.ts

@@ -54,8 +54,10 @@ export declare class ViessmannPlatform implements DynamicPlatformPlugin {
     setupDHWAccessory(installation: ViessmannInstallation, gateway: ViessmannGateway, device: ViessmannDevice, features: ViessmannFeature[]): Promise<void>;
     setupHeatingCircuitAccessories(installation: ViessmannInstallation, gateway: ViessmannGateway, device: ViessmannDevice, features: ViessmannFeature[]): Promise<void>;
     setupEnergyAccessory(installation: ViessmannInstallation, gateway: ViessmannGateway, device: ViessmannDevice, features: ViessmannFeature[]): Promise<void>;
+    private setupRoomSensorDiscovery;
     updateAllDevices(): Promise<void>;
     private updateCycleComplete;
+    private writeApiStatusFile;
     private adjustRefreshInterval;
     private sleep;
     private startHealthMonitoring;

package/dist/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,GAAG,EAGH,qBAAqB,EACrB,MAAM,EACN,iBAAiB,EACjB,cAAc,EACd,OAAO,EACP,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAExE,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACrI,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAgB,MAAM,2BAA2B,CAAC;AAOrI,qBAAa,iBAAkB,YAAW,qBAAqB;aA2B3C,GAAG,EAAE,MAAM;aACX,MAAM,EAAE,uBAAuB,GAAG,cAAc;aAChD,GAAG,EAAE,GAAG;IA5B1B,SAAgB,OAAO,EAAE,OAAO,OAAO,CAAC;IACxC,SAAgB,cAAc,EAAE,OAAO,cAAc,CAAC;IAEtD,SAAgB,WAAW,EAAE,iBAAiB,EAAE,CAAM;IACtD,SAAgB,YAAY,EAAG,YAAY,CAAC;IAC5C,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,YAAY,CAAC,CAAiB;IACtC,OAAO,CAAC,qBAAqB,CAAC,CAAiB;IAC/C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,iBAAiB,CAAK;IAG9B,OAAO,CAAC,oBAAoB,CAA0C;IACtE,OAAO,CAAC,iBAAiB,CAMvB;gBAGgB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,uBAAuB,GAAG,cAAc,EAChD,GAAG,EAAE,GAAG;IA+F1B,OAAO,CAAC,cAAc;IAmCtB,OAAO,CAAC,uBAAuB;YAQjB,wBAAwB;YA8CxB,iCAAiC;YA+CjC,iCAAiC;YAoHjC,8BAA8B;YA2D9B,yCAAyC;IA4BhD,4BAA4B,CACjC,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,MAAkD,GAC1D,IAAI;IAgBP,OAAO,CAAC,yBAAyB;IAW1B,oBAAoB,IAAI;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;KACvB;IAWD,kBAAkB,CAAC,SAAS,EAAE,iBAAiB;IAKzC,eAAe;IAuDrB,OAAO,CAAC,oBAAoB;IA8B5B,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA+CrB,sBAAsB,CAAC,YAAY,EAAE,qBAAqB,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe;IA8B9G,oBAAoB,CACxB,YAAY,EAAE,qBAAqB,EACnC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,gBAAgB,EAAE;IAiCxB,iBAAiB,CACrB,YAAY,EAAE,qBAAqB,EACnC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,gBAAgB,EAAE;IAgCxB,8BAA8B,CAClC,YAAY,EAAE,qBAAqB,EACnC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,gBAAgB,EAAE;IAuCxB,oBAAoB,CACxB,YAAY,EAAE,qBAAqB,EACnC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,gBAAgB,EAAE;IAiExB,gBAAgB;IA2HtB,OAAO,CAAC,mBAAmB;IAqC3B,OAAO,CAAC,qBAAqB;IA2B7B,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,eAAe;IAiFhB,kBAAkB;;;;;;;;;IAKlB,iBAAiB;;;;;;;;;0BAnrBR,MAAM;+BACD,MAAM;2BACV,MAAM;yBACR,MAAM;4BACH,MAAM;4BACN,MAAM;2BACP,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAosBxB"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}

package/dist/platform.js

@@ -40,6 +40,8 @@ const boiler_accessory_1 = require("./accessories/boiler-accessory");
 const dhw_accessory_1 = require("./accessories/dhw-accessory");
 const heating_circuit_accessory_1 = require("./accessories/heating-circuit-accessory");
 const energy_accessory_1 = require("./accessories/energy-accessory");
+const room_sensor_accessory_1 = require("./accessories/room-sensor-accessory");
+const fs = __importStar(require("fs"));
 const settings_1 = require("./settings");
 class ViessmannPlatform {
     log;
@@ -116,7 +118,8 @@ class ViessmannPlatform {
                             }
                         }
                     }
-                    const serverArgs = ['--port', String(reportPort), '--path', reportServerPath];
+                    const reportTimeout = this.config.reportServerTimeout ?? 300;
+                    const serverArgs = ['--port', String(reportPort), '--path', reportServerPath, '--timeout', String(reportTimeout)];
                     if (this.config.debug)
                         serverArgs.push('--debug');
                     const { execFile } = require('child_process');
@@ -127,13 +130,12 @@ class ViessmannPlatform {
                     child.on('error', (err) => {
                         this.log.warn(`Report server failed to start: ${err.message}`);
                     });
-                    this.log.info(`Report server ready — open from any device on your network:`);
-                    this.log.info(`  🌐 http://${lanIP}:${reportPort}`);
-                    if (this.config.debug) {
-                        this.log.debug(`  (also available as http://localhost:${reportPort} on this host)`);
-                        this.log.debug(`  Data path: ${reportServerPath}`);
-                        this.log.debug(`  Script: ${reportScript}`);
-                    }
+                    this.log.info('═'.repeat(60));
+                    this.log.info('📊 Viessmann Report Server');
+                    this.log.info(`   Open from any device: http://${lanIP}:${reportPort}`);
+                    this.log.info('═'.repeat(60));
+                    this.log.debug(`  Data path: ${reportServerPath}`);
+                    this.log.debug(`  Script:    ${reportScript}`);
                 }
                 catch (e) {
                     this.log.warn(`Could not start report server: ${e.message}`);
@@ -547,6 +549,10 @@ class ViessmannPlatform {
             await this.setupHeatingCircuitAccessories(installation, gateway, device, features);
             // Setup Energy / Heat Pump accessory (PV, battery, wallbox, electric DHW, Wärmepumpe)
             await this.setupEnergyAccessory(installation, gateway, device, features);
+            // TRV / Room Sensor discovery mode (logs all features, creates TemperatureSensor per device)
+            if (this.config.features?.enableRoomSensorDiscovery) {
+                await this.setupRoomSensorDiscovery(installation, gateway, device, features);
+            }
         }
         catch (error) {
             const status = error?.response?.status;
@@ -688,6 +694,39 @@ class ViessmannPlatform {
             this.api.registerPlatformAccessories(settings_1.PLUGIN_NAME, 'ViessmannPlatform', [accessory]);
         }
     }
+    // ── TRV / Room Sensor Discovery ──────────────────────────────────────────
+    // Enabled via features.enableRoomSensorDiscovery = true.
+    // Creates a TemperatureSensor accessory for each device that exposes a
+    // temperature reading. Full feature dump goes to Homebridge logs so we can
+    // identify the correct API paths for a given TRV model.
+    async setupRoomSensorDiscovery(installation, gateway, device, features) {
+        // Run the feature scan (always logs, regardless of whether we find a temp)
+        const result = (0, room_sensor_accessory_1.discoverRoomSensorData)(this, device, features);
+        // Only create a HomeKit accessory if we found at least one temperature value
+        if (result.currentTemp === undefined) {
+            this.log.debug(`[RoomDiscovery] Device ${device.id} — no temperature found, skipping HomeKit accessory`);
+            return;
+        }
+        const customNames = this.config.customNames ?? {};
+        const prefix = customNames.installationPrefix || installation.description || String(installation.id);
+        const modelLabel = device.modelId || device.id;
+        const name = `${prefix} Room ${modelLabel}`;
+        const uuid = this.api.hap.uuid.generate(`room-sensor-${installation.id}-${device.id}`);
+        let accessory = this.accessories.find(a => a.UUID === uuid);
+        if (!accessory) {
+            this.log.info(`[RoomDiscovery] Creating new TemperatureSensor: "${name}"`);
+            accessory = new this.api.platformAccessory(name, uuid);
+            accessory.context = { installation, gateway, device, isRoomSensor: true };
+            this.api.registerPlatformAccessories('homebridge-viessmann-vicare', 'ViessmannPlatform', [accessory]);
+            this.accessories.push(accessory);
+        }
+        else {
+            this.log.debug(`[RoomDiscovery] Restoring cached accessory: "${name}"`);
+        }
+        const handler = new room_sensor_accessory_1.ViessmannRoomSensorAccessory(this, accessory, installation, gateway, device, features);
+        // Attach updateHandler so the main refresh loop can call update()
+        accessory.updateHandler = (feats) => handler.update(feats);
+    }
     async updateAllDevices() {
         // Prevent overlapping updates
         if (this.isUpdating) {
@@ -826,9 +865,51 @@ class ViessmannPlatform {
                 const healthScore = this.viessmannAPI.getAPIHealthScore();
                 const healthStatus = this.viessmannAPI.getAPIHealthStatus();
                 this.log.debug(`📊 API Health: ${healthScore}/100 (${healthStatus})`);
+                this.writeApiStatusFile(healthScore, healthStatus);
             }
         }
     }
+    // ── API Status File ─────────────────────────────────────────────────────────
+    // Written after each successful update cycle.
+    // Read by viessmann-report-server.js and auth-manager status page to show
+    // API usage percentage, health score, and rate limit info in the web UI.
+    // Viessmann documented daily limit: 1450 requests/day.
+    writeApiStatusFile(healthScore, healthStatus) {
+        try {
+            const storagePath = this.api.user.storagePath();
+            const metrics = this.viessmannAPI.getAPIMetrics();
+            const rateLimitSt = this.viessmannAPI.getRateLimitStatus();
+            const DAILY_LIMIT = 1450; // Viessmann API documented daily quota
+            const status = {
+                timestamp: new Date().toISOString(),
+                healthScore,
+                healthStatus,
+                totalRequests: metrics.totalRequests,
+                successfulRequests: metrics.successfulRequests,
+                failedRequests: metrics.failedRequests,
+                rateLimitHits: metrics.rateLimitHits,
+                errorRate: parseFloat(metrics.errorRate.toFixed(1)),
+                avgResponseTime: Math.round(metrics.averageResponseTime),
+                requestsPerMinute: metrics.requestsPerMinute,
+                isRateLimited: rateLimitSt.isLimited,
+                rateLimitWaitSec: rateLimitSt.waitSeconds ?? 0,
+                dailyQuotaExceeded: rateLimitSt.dailyQuotaExceeded,
+                // Estimated daily usage — resets with metrics (every 24h)
+                // requestsPerMinute × 60 × 24 gives a rough projection
+                dailyEstimatedReqs: Math.round(metrics.requestsPerMinute * 60 * 24),
+                dailyLimitTotal: DAILY_LIMIT,
+                dailyUsagePct: Math.min(100, parseFloat((metrics.totalRequests / DAILY_LIMIT * 100).toFixed(1))),
+                pluginVersion: '2.0.71',
+                refreshInterval: this.config.refreshInterval || 120000,
+            };
+            const filePath = require('path').join(storagePath, 'viessmann-api-status.json');
+            fs.writeFileSync(filePath, JSON.stringify(status, null, 2), 'utf8');
+            this.log.debug(`📊 API status written: health=${healthScore}/100, dailyUsage=${status.dailyUsagePct}%`);
+        }
+        catch (e) {
+            this.log.debug(`📊 Could not write API status file: ${e.message}`);
+        }
+    }
     adjustRefreshInterval(increase) {
         if (this.config.enableRateLimitProtection === false) {
             return;

package/dist/settings.d.ts

@@ -9,7 +9,7 @@ export declare const PLUGIN_NAME = "homebridge-viessmann-vicare";
 /**
  * Plugin version for User-Agent and logging
  */
-export declare const PLUGIN_VERSION = "2.0.69";
+export declare const PLUGIN_VERSION = "2.0.71";
 /**
  * Default configuration values
  */
@@ -49,12 +49,14 @@ export declare const DEFAULT_CONFIG: {
         enableTemperaturePrograms: boolean;
         enableQuickSelections: boolean;
         enableBurnerStatus: boolean;
+        enableRoomSensorDiscovery: boolean;
     };
     advanced: {
         maxConsecutiveErrors: number;
         deviceUpdateDelay: number;
         userAgent: string;
     };
+    reportServerTimeout: number;
     monitoring: {
         enableHealthReports: boolean;
         healthReportInterval: number;

package/dist/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,WAAW,gCAAgC,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;mCAOK,MAAM;kCACP,MAAM,iBAAiB,MAAM;mCAE5B,MAAM,iBAAiB,MAAM,YAAY,MAAM;kCAEhD,MAAM,iBAAiB,MAAM,YAAY,MAAM,eAAe,MAAM;kCAEpE,MAAM,iBAAiB,MAAM,YAAY,MAAM,eAAe,MAAM,eAAe,MAAM;;CAGtH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;6BAmBN,MAAM;+BACJ,MAAM;2BACV,MAAM;2BACN,MAAM;;;;;;;CAS5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAmB3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;CAmBlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;CAK/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;CAY1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;CAgBhC,CAAC"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,WAAW,gCAAgC,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;mCAOK,MAAM;kCACP,MAAM,iBAAiB,MAAM;mCAE5B,MAAM,iBAAiB,MAAM,YAAY,MAAM;kCAEhD,MAAM,iBAAiB,MAAM,YAAY,MAAM,eAAe,MAAM;kCAEpE,MAAM,iBAAiB,MAAM,YAAY,MAAM,eAAe,MAAM,eAAe,MAAM;;CAGtH,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;6BAmBN,MAAM;+BACJ,MAAM;2BACV,MAAM;2BACN,MAAM;;;;;;;CAS5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAmB3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;CAmBlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;CAK/B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;CAY1B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;CAgBhC,CAAC"}

package/dist/settings.js

@@ -12,7 +12,7 @@ exports.PLUGIN_NAME = 'homebridge-viessmann-vicare';
 /**
  * Plugin version for User-Agent and logging
  */
-exports.PLUGIN_VERSION = '2.0.69';
+exports.PLUGIN_VERSION = '2.0.71';
 /**
  * Default configuration values
  */
@@ -53,12 +53,15 @@ exports.DEFAULT_CONFIG = {
         enableTemperaturePrograms: true,
         enableQuickSelections: true,
         enableBurnerStatus: true,
+        // TRV / Smart Climate discovery (verbose — use only for diagnostics)
+        enableRoomSensorDiscovery: false,
     },
     advanced: {
         maxConsecutiveErrors: 5,
         deviceUpdateDelay: 1000,
         userAgent: `homebridge-viessmann-vicare/${exports.PLUGIN_VERSION}`,
     },
+    reportServerTimeout: 600, // seconds — default 10 min; RPi3: ~365s/90days ~1460s/365days
     monitoring: {
         enableHealthReports: true,
         healthReportInterval: 3600000, // 1 hour

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-viessmann-vicare",
-  "version": "2.0.69",
+  "version": "2.0.71",
   "description": "Complete Homebridge plugin for Viessmann ViCare heating systems with full control capabilities, advanced rate limiting protection, and intelligent cache management",
   "main": "dist/index.js",
   "scripts": {

package/viessmann-report-server.js

@@ -27,10 +27,12 @@ const { execFile, spawn } = require('child_process');
 const args   = process.argv.slice(2);
 const getArg = (flag, def) => { const i = args.indexOf(flag); return i !== -1 && args[i+1] ? args[i+1] : def; };
 
-const PORT    = parseInt(getArg('--port',   process.env.REPORT_SERVER_PORT || '3001'), 10);
-const HB_PATH = getArg('--path',   process.env.HB_PATH || '/var/lib/homebridge');
-const SCRIPT  = getArg('--script', path.join(__dirname, 'viessmann-report.js'));
+const PORT    = parseInt(getArg('--port',    process.env.REPORT_SERVER_PORT || '3001'), 10);
+const HB_PATH = getArg('--path',    process.env.HB_PATH || '/var/lib/homebridge');
+const SCRIPT  = getArg('--script',  path.join(__dirname, 'viessmann-report.js'));
 const DEBUG   = args.includes('--debug') || process.env.DEBUG_REPORT === '1';
+// --timeout <seconds> passed from plugin config (reportServerTimeout, default 300)
+const TIMEOUT_SEC = parseInt(getArg('--timeout', '300'), 10);
 
 // ── Debug logger ───────────────────────────────────────────────────────────
 function dbg(...parts) {
@@ -93,7 +95,7 @@ function safeNum(val) {
 // CSV files (e.g. 90 days = ~26 000 rows). The default 60 s was insufficient.
 // Raised to 300 s (5 minutes) which comfortably handles the largest datasets.
 
-const REPORT_TIMEOUT_MS = 300_000; // 5 minutes
+const REPORT_TIMEOUT_MS = Math.min(Math.max(TIMEOUT_SEC, 60), 1800) * 1000; // from --timeout arg (clamped 60–1800s)
 
 function generateReport(params) {
   return new Promise((resolve, reject) => {
@@ -193,7 +195,7 @@ function generateReport(params) {
 
 // ── UI HTML ────────────────────────────────────────────────────────────────
 
-function buildUI(installations) {
+function buildUI(installations, apiStatus) {
   const today = new Date().toLocaleDateString('en-GB', { day:'2-digit', month:'short', year:'numeric' });
   const instOptions = installations.length === 0
     ? '<option value="">No CSV found — check path</option>'
@@ -201,6 +203,51 @@ function buildUI(installations) {
         '<option value="' + id + '">' + (id ? 'Installation ' + id : 'Default (no ID)') + '</option>'
       ).join('');
 
+
+  // Build API status card from shared status file
+  const apiCardHtml = (() => {
+    if (!apiStatus) {
+      return `<div class="api-card">
+        <div class="api-card-title">🌐 API Usage</div>
+        <div class="api-row"><span class="api-lbl">Status</span><span class="api-val" style="color:var(--muted)">No data yet — waiting for first update cycle</span></div>
+      </div>`;
+    }
+    const pct     = apiStatus.dailyUsagePct ?? 0;
+    const health  = apiStatus.healthScore ?? 0;
+    const pctCls  = pct > 80 ? 'bad' : pct > 50 ? 'warn' : 'ok';
+    const hCls    = health >= 85 ? 'ok' : health >= 60 ? 'warn' : 'bad';
+    const rlTxt   = apiStatus.isRateLimited
+      ? `<span class="api-val bad">🚫 Rate limited — wait ${apiStatus.rateLimitWaitSec}s</span>`
+      : (apiStatus.dailyQuotaExceeded
+          ? `<span class="api-val bad">🚫 Daily quota exceeded</span>`
+          : `<span class="api-val ok">✓ OK</span>`);
+    const age     = Math.round((Date.now() - new Date(apiStatus.timestamp).getTime()) / 1000);
+    const ageStr  = age < 120 ? `${age}s ago` : `${Math.round(age/60)}m ago`;
+    return `<div class="api-card">
+      <div class="api-card-title">🌐 API Usage (Viessmann limit: ${apiStatus.dailyLimitTotal ?? 1450} req/day)</div>
+      <div class="api-row">
+        <span class="api-lbl">Daily usage (est.)</span>
+        <span class="api-val">
+          <span class="bar-wrap"><span class="bar-fill ${pctCls}" style="width:${Math.min(pct,100)}%"></span></span>
+          <span class="${pctCls}">${pct}%</span>
+          &nbsp;<span style="color:var(--muted);font-size:10px">(~${apiStatus.dailyEstimatedReqs ?? '?'} req/day)</span>
+        </span>
+      </div>
+      <div class="api-row">
+        <span class="api-lbl">Health score</span>
+        <span class="api-val">
+          <span class="bar-wrap"><span class="bar-fill ${hCls}" style="width:${health}%"></span></span>
+          <span class="${hCls}">${health}/100</span>
+          &nbsp;<span style="color:var(--muted);font-size:10px">${apiStatus.healthStatus ?? ''}</span>
+        </span>
+      </div>
+      <div class="api-row"><span class="api-lbl">Rate limit</span>${rlTxt}</div>
+      <div class="api-row"><span class="api-lbl">Avg response</span><span class="api-val">${apiStatus.avgResponseTime ?? 0} ms</span></div>
+      <div class="api-row"><span class="api-lbl">Error rate</span><span class="api-val ${apiStatus.errorRate > 10 ? 'bad' : apiStatus.errorRate > 5 ? 'warn' : 'ok'}">${apiStatus.errorRate ?? 0}%</span></div>
+      <div class="api-row"><span class="api-lbl">Last updated</span><span class="api-val" style="color:var(--muted)">${ageStr}</span></div>
+    </div>`;
+  })();
+
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -254,6 +301,16 @@ input:focus,select:focus{outline:none;border-color:var(--accent)}
 @keyframes spin{to{transform:rotate(360deg)}}
 .spinner{display:inline-block;width:13px;height:13px;border:2px solid rgba(249,115,22,.3);border-top-color:var(--accent);border-radius:50%;animation:spin .7s linear infinite;vertical-align:middle;margin-right:6px}
 footer{margin-top:36px;font-family:'Space Mono',monospace;font-size:10px;color:var(--muted);text-align:center;opacity:.4}
+.api-card{background:var(--surface);border:1px solid var(--border);border-radius:var(--r);padding:16px 20px;width:100%;max-width:560px;margin-bottom:14px}
+.api-card-title{font-family:'Space Mono',monospace;font-size:10px;text-transform:uppercase;letter-spacing:2px;color:var(--accent);margin-bottom:12px}
+.api-row{display:flex;justify-content:space-between;align-items:center;padding:6px 0;border-bottom:1px solid var(--border);font-size:12px}
+.api-row:last-child{border-bottom:none}
+.api-lbl{color:var(--muted);font-family:'Space Mono',monospace;font-size:11px}
+.api-val{font-weight:600;font-family:'Space Mono',monospace;font-size:11px}
+.api-val.ok{color:var(--good)}.api-val.warn{color:var(--warn)}.api-val.bad{color:var(--bad)}
+.bar-wrap{width:100px;height:6px;background:var(--border);border-radius:3px;overflow:hidden;display:inline-block;vertical-align:middle;margin-right:6px}
+.bar-fill{height:100%;border-radius:3px}
+.bar-fill.ok{background:var(--good)}.bar-fill.warn{background:var(--warn)}.bar-fill.bad{background:var(--bad)}
 </style>
 </head>
 <body>
@@ -343,6 +400,7 @@ footer{margin-top:36px;font-family:'Space Mono',monospace;font-size:10px;color:v
   Generate Report
 </button>
 <div id="status"></div>
+${apiCardHtml}
 <footer>homebridge-viessmann-vicare &nbsp;·&nbsp; report server &nbsp;·&nbsp; ${HB_PATH} &nbsp;·&nbsp; ${LAN_IP}:${PORT}</footer>
 
 <script>
@@ -422,7 +480,8 @@ const server = http.createServer(async (req, res) => {
 
   if (pathname === '/' || pathname === '') {
     const installations = detectInstallations();
-    const html = buildUI(installations);
+    const apiStatus = readApiStatus(HB_PATH);
+    const html = buildUI(installations, apiStatus);
     res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
     res.end(html);
     dbg(`← 200 / (${Date.now()-t0}ms, ${installations.length} installation(s))`);
@@ -490,7 +549,7 @@ if (require.main === module) {
     console.log('[ReportServer] ═══════════════════════════════════════════════');
     console.log(`[ReportServer] 🌐 Open from any device: http://${LAN_IP}:${PORT}`);
     console.log(`[ReportServer] 📁 Data path:            ${HB_PATH}`);
-    console.log(`[ReportServer] ⏱️  Report timeout:       ${REPORT_TIMEOUT_MS/1000}s`);
+    console.log(`[ReportServer] ⏱️  Report timeout:       ${REPORT_TIMEOUT_MS/1000}s (--timeout ${TIMEOUT_SEC}s)`);
     if (DEBUG) {
       console.log(`[ReportServer] 🔍 Debug mode:           ON`);
       console.log(`[ReportServer]    Script:   ${SCRIPT}`);