homebridge-hap-homematic 0.4.1 → 0.5.0

package/README.md

@@ -1,9 +1,6 @@
 # homebridge-hap-homematic
 
-<!--
-  Modified by california444 (2026) for homebridge-hap-homematic,
-  a hard fork of Homebridge-Homematic-HAP (Apache-2.0). See NOTICE.
--->
+<!-- Modified by california444 (2026). See NOTICE. -->
 
 [![Release](https://github.com/california444/homebridge-hap-homematic/actions/workflows/release.yml/badge.svg)](https://github.com/california444/homebridge-hap-homematic/actions/workflows/release.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

package/config.schema.json

@@ -6,7 +6,6 @@
   "customUi": true,
   "customUiPath": "./homebridge-ui",
   "headerDisplay": "**HomeMatic (BidCos-RF) / HomematicIP (HmIP-RF)** plugin for a CCU / OpenCCU, using XML-RPC only. Use the **custom UI** below to discover devices and map channels to HomeKit.",
-  "footerDisplay": "Hard fork of [Homebridge-Homematic-HAP](https://github.com/matthiaseinig/Homebridge-Homematic-HAP), which builds on [thkl/hap-homematic](https://github.com/thkl/hap-homematic) and [thkl/homebridge-homematic](https://github.com/thkl/homebridge-homematic). Apache-2.0.",
   "schema": {
     "type": "object",
     "properties": {

package/homebridge-ui/public/app.js

@@ -316,7 +316,7 @@ function viewChannels(host) {
   host.innerHTML = `
     <div class="hgui-stats mt-3">
       ${statHTML('Channels', configuredChannels().length, 'in HomeKit')}
-      ${statHTML('Devices', discovered, discovered ? 'discovered on the CCU' : 'not discovered yet')}
+      ${statHTML('Devices', discovered, discoverySourceText())}
       <div class="hgui-card d-flex flex-column justify-content-center gap-1">
         <button class="btn btn-primary" id="hgui-discover-btn">Discover</button>
         <div class="hgui-meta">Reload devices and channels from the CCU.</div>
@@ -369,7 +369,7 @@ function viewChannels(host) {
   $('hgui-filterType-channels').value   = channelTypes.has(state.ui.filterType.channels) ? state.ui.filterType.channels : 'all';
   $('hgui-sort-channels').value         = state.ui.sort.channels;
 
-  $('hgui-discover-btn').addEventListener('click', onDiscover);
+  $('hgui-discover-btn').addEventListener('click', () => onDiscover());
   $('hgui-help').addEventListener('toggle', (e) => { state.ui.helpOpen = e.target.open; });
 
   $('hgui-search-channels').addEventListener('input', (e) => {
@@ -1009,18 +1009,50 @@ async function onTestConnection() {
   } finally { spinner(false); }
 }
 
-async function onDiscover() {
-  spinner(true);
+/**
+ * Live discovery from the CCU (listDevices, no radio traffic).
+ * `quiet`: no spinner and no success toast (automatic fallback on open);
+ * errors are always shown.
+ */
+async function onDiscover({ quiet = false } = {}) {
+  if (!quiet) spinner(true);
   try {
     const res = await homebridge.request('/discover', state.cfg);
     state.discovered = res;
     rerender();
-    toast('success', 
-      `${res.devices.length} devices`,
-      'Discovery complete');
+    if (!quiet) toast('success', `${res.devices.length} devices`, 'Discovery complete');
   } catch (err) {
     toast('error', err.message, 'Discovery');
-  } finally { spinner(false); }
+  } finally { if (!quiet) spinner(false); }
+}
+
+/**
+ * The device list the plugin saved at its last start. Returns false if
+ * there is none, so the caller can fall back to a live discovery.
+ */
+async function loadCachedDiscovery() {
+  try {
+    const res = await homebridge.request('/discover/cached');
+    if (!res?.devices?.length) return false;
+    state.discovered = res;
+    rerender();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** "live, 22:05" / "saved by the plugin, 12.11. 22:05" for the Devices box. */
+function discoverySourceText() {
+  const d = state.discovered;
+  if (!d.devices?.length) return 'not discovered yet';
+  const at = d.fetchedAt ? new Date(d.fetchedAt) : null;
+  const when = at && !Number.isNaN(at.getTime())
+    ? at.toLocaleString(undefined, { day: '2-digit', month: '2-digit', hour: '2-digit', minute: '2-digit' })
+    : '';
+  return d.source === 'cache'
+    ? `saved by the plugin${when ? `, ${when}` : ''}`
+    : `live from the CCU${when ? `, ${when}` : ''}`;
 }
 
 /**
@@ -1098,16 +1130,18 @@ async function init() {
     if (e.key === 'Escape' && state.nav.length) popNav();
   });
 
-  // Initial tab: Settings until a CCU is configured, then Channels with
-  // a background Discover so the list fills in on its own.
+  // Initial tab: Settings until a CCU is configured, then Channels. The
+  // device list comes from the plugin's discovery.json (no CCU call);
+  // only if there is none (plugin never started) a quiet live discovery
+  // runs. The Discover button always asks the CCU.
   const isConfigured = !!state.cfg.ccuIp && state.cfg.ccuIp.length > 0;
   if (!isConfigured) {
     navigate('settings');
   } else {
     navigate('channels');
-    // Fire-and-forget; failures fall back to the empty state with a
-    // hint already in place. No spinner — user can still navigate.
-    onDiscover().catch(() => { /* errors already toasted by onDiscover */ });
+    loadCachedDiscovery()
+      .then((ok) => (ok ? undefined : onDiscover({ quiet: true })))
+      .catch(() => { /* errors already toasted by onDiscover */ });
   }
 }
 

package/homebridge-ui/server.js

@@ -148,7 +148,8 @@ var RequestError = class _RequestError extends Error {
 };
 
 // homebridge-ui/server.src.js
-import { CcuClient } from "../dist/src/ccu/CcuClient.js";
+import { CcuClient, toDevices } from "../dist/src/ccu/CcuClient.js";
+import { DISCOVERY_CACHE_FILE } from "../dist/src/ccu/Discovery.js";
 import { resolveConfig, ConfigError } from "../dist/src/util/config.js";
 import { PrefixedLogger } from "../dist/src/util/logger.js";
 import {
@@ -183,6 +184,15 @@ var PLUGIN_VERSION = (() => {
 var MAX_DEVICES_JSON_BYTES = 512 * 1024;
 var KNOWN_SERVICES = new Set(SERVICE_DEFINITIONS.map((s) => s.key));
 var DEVICE_SERVICES = new Set(SERVICE_DEFINITIONS.filter((s) => s.scope === "device").map((s) => s.key));
+function enrich(devices) {
+  return devices.map((d) => ({
+    ...d,
+    channels: d.channels.map((c) => ({
+      ...c,
+      suggestedServices: servicesForChannelType(c.type).map((s) => s.key)
+    }))
+  }));
+}
 var UiLogger = class {
   info(...args) {
     console.log("[ui]", ...args);
@@ -209,6 +219,7 @@ var HapHomematicUiServer = class extends HomebridgePluginUiServer {
     this.onRequest("/services", () => this.handleServices());
     this.onRequest("/test-connection", (payload) => this.handleTestConnection(payload));
     this.onRequest("/discover", (payload) => this.handleDiscover(payload));
+    this.onRequest("/discover/cached", () => this.handleCachedDiscovery());
     this.onRequest("/network", () => this.handleNetwork());
     this.onRequest("/devices/get", () => this.handleGetDevices());
     this.onRequest("/devices/put", (payload) => this.handlePutDevices(payload));
@@ -259,14 +270,7 @@ var HapHomematicUiServer = class extends HomebridgePluginUiServer {
     const ccu = new CcuClient({ config, log });
     try {
       const devices = await ccu.listDevices();
-      const enrichedDevices = devices.map((d) => ({
-        ...d,
-        channels: d.channels.map((c) => ({
-          ...c,
-          suggestedServices: servicesForChannelType(c.type).map((s) => s.key)
-        }))
-      }));
-      return { devices: enrichedDevices };
+      return { devices: enrich(devices), source: "live", fetchedAt: (/* @__PURE__ */ new Date()).toISOString() };
     } catch (err) {
       throw new RequestError(`Discovery failed: ${err.message}`, { status: 502 });
     } finally {
@@ -276,6 +280,30 @@ var HapHomematicUiServer = class extends HomebridgePluginUiServer {
       }
     }
   }
+  /**
+   * The device list the plugin saved at its last start (discovery.json),
+   * without asking the CCU. `devices: []` if there is none (plugin never
+   * started) or it is unreadable; the UI then discovers live.
+   */
+  async handleCachedDiscovery() {
+    let raw;
+    try {
+      raw = await this.storage().readJson(DISCOVERY_CACHE_FILE);
+    } catch (err) {
+      console.warn("[ui] cannot read %s: %s", DISCOVERY_CACHE_FILE, err.message);
+      return { devices: [], source: "cache" };
+    }
+    const interfaces = raw && typeof raw === "object" && raw.version === 1 && raw.interfaces && typeof raw.interfaces === "object" ? raw.interfaces : {};
+    const devices = [];
+    const stamps = [];
+    for (const [id, entry] of Object.entries(interfaces)) {
+      if (!entry || !Array.isArray(entry.devices)) continue;
+      devices.push(...toDevices(entry.devices, id));
+      if (typeof entry.fetchedAt === "string") stamps.push(entry.fetchedAt);
+    }
+    stamps.sort();
+    return { devices: enrich(devices), source: "cache", fetchedAt: stamps[0] };
+  }
   /** Local IPv4 addresses, offered as callback address (5.1). */
   handleNetwork() {
     const out = [];

package/homebridge-ui/server.src.js

@@ -46,7 +46,8 @@ const PLUGIN_VERSION = (() => {
   return version;
 })();
 
-import { CcuClient } from '../dist/src/ccu/CcuClient.js';
+import { CcuClient, toDevices } from '../dist/src/ccu/CcuClient.js';
+import { DISCOVERY_CACHE_FILE } from '../dist/src/ccu/Discovery.js';
 import { resolveConfig, ConfigError } from '../dist/src/util/config.js';
 import { PrefixedLogger } from '../dist/src/util/logger.js';
 import {
@@ -66,6 +67,17 @@ const MAX_DEVICES_JSON_BYTES = 512 * 1024;
 const KNOWN_SERVICES = new Set(SERVICE_DEFINITIONS.map((s) => s.key));
 const DEVICE_SERVICES = new Set(SERVICE_DEFINITIONS.filter((s) => s.scope === 'device').map((s) => s.key));
 
+/** Annotate channels with the services that can handle them. */
+function enrich(devices) {
+  return devices.map((d) => ({
+    ...d,
+    channels: d.channels.map((c) => ({
+      ...c,
+      suggestedServices: servicesForChannelType(c.type).map((s) => s.key),
+    })),
+  }));
+}
+
 class UiLogger {
   info(...args)    { console.log('[ui]', ...args); }
   success(...args) { console.log('[ui]', ...args); }
@@ -83,6 +95,7 @@ class HapHomematicUiServer extends HomebridgePluginUiServer {
     this.onRequest('/services', () => this.handleServices());
     this.onRequest('/test-connection', (payload) => this.handleTestConnection(payload));
     this.onRequest('/discover', (payload) => this.handleDiscover(payload));
+    this.onRequest('/discover/cached', () => this.handleCachedDiscovery());
     this.onRequest('/network', () => this.handleNetwork());
     this.onRequest('/devices/get', () => this.handleGetDevices());
     this.onRequest('/devices/put', (payload) => this.handlePutDevices(payload));
@@ -139,17 +152,7 @@ class HapHomematicUiServer extends HomebridgePluginUiServer {
     const ccu = new CcuClient({ config, log });
     try {
       const devices = await ccu.listDevices();
-
-      // Annotate channels with suggested services.
-      const enrichedDevices = devices.map((d) => ({
-        ...d,
-        channels: d.channels.map((c) => ({
-          ...c,
-          suggestedServices: servicesForChannelType(c.type).map((s) => s.key),
-        })),
-      }));
-
-      return { devices: enrichedDevices };
+      return { devices: enrich(devices), source: 'live', fetchedAt: new Date().toISOString() };
     } catch (err) {
       throw new RequestError(`Discovery failed: ${err.message}`, { status: 502 });
     } finally {
@@ -157,6 +160,34 @@ class HapHomematicUiServer extends HomebridgePluginUiServer {
     }
   }
 
+  /**
+   * The device list the plugin saved at its last start (discovery.json),
+   * without asking the CCU. `devices: []` if there is none (plugin never
+   * started) or it is unreadable; the UI then discovers live.
+   */
+  async handleCachedDiscovery() {
+    let raw;
+    try {
+      raw = await this.storage().readJson(DISCOVERY_CACHE_FILE);
+    } catch (err) {
+      console.warn('[ui] cannot read %s: %s', DISCOVERY_CACHE_FILE, err.message);
+      return { devices: [], source: 'cache' };
+    }
+    const interfaces = raw && typeof raw === 'object' && raw.version === 1 && raw.interfaces && typeof raw.interfaces === 'object'
+      ? raw.interfaces
+      : {};
+    const devices = [];
+    const stamps = [];
+    for (const [id, entry] of Object.entries(interfaces)) {
+      if (!entry || !Array.isArray(entry.devices)) continue;
+      devices.push(...toDevices(entry.devices, id));
+      if (typeof entry.fetchedAt === 'string') stamps.push(entry.fetchedAt);
+    }
+    // The oldest interface decides how fresh the list is.
+    stamps.sort();
+    return { devices: enrich(devices), source: 'cache', fetchedAt: stamps[0] };
+  }
+
   /** Local IPv4 addresses, offered as callback address (5.1). */
   handleNetwork() {
     const out = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-hap-homematic",
-  "version": "0.4.1",
-  "description": "Homebridge plugin for HomeMatic / HomematicIP devices on a CCU / OpenCCU, using XML-RPC only. Hard fork of matthiaseinig/Homebridge-Homematic-HAP (homebridge-homematic-hap); not affiliated with thkl/hap-homematic.",
+  "version": "0.5.0",
+  "description": "Homebridge plugin for HomeMatic / HomematicIP devices on a CCU / OpenCCU, using XML-RPC only.",
   "type": "module",
   "license": "Apache-2.0",
   "author": {