iobroker.zigbee2mqtt 3.1.1 → 3.1.5

package/lib/imageController.js

@@ -2,42 +2,49 @@ const axios = require('axios').default;
 const sharp = require('sharp');
 
 /**
- *
+ * Lädt Geräte-Icons von zigbee2mqtt.io herunter, cacht sie im ioBroker-Dateisystem
+ * und skaliert sie auf die konfigurierte Größe.
  */
 class ImageController {
     /**
+     * Erstellt eine neue ImageController-Instanz.
      *
-     * @param adapter
+     * @param {object} adapter Die ioBroker-Adapter-Instanz
      */
     constructor(adapter) {
         this.adapter = adapter;
     }
 
     /**
+     * Bereinigt eine Model-ID für die Verwendung in einer URL (ersetzt '/' durch '_').
      *
-     * @param modelName
+     * @param {string} modelName Die zu bereinigende Model-ID
+     * @returns {string}         Bereinigte Model-ID oder 'NA' wenn leer
      */
     sanitizeModelIDForImageUrl(modelName) {
-        if (!modelName) {return 'NA';}
-        const modelNameString = modelName.replace('/', '_');
+        if (!modelName) { return 'NA'; }
         // eslint-disable-next-line no-control-regex
-        return modelNameString.replace(/\u0000/g, '');
+        return modelName.replace(/\//g, '_').replace(/\u0000/g, '');
     }
 
     /**
+     * Bereinigt einen Z2M-Gerätenamen für die Verwendung in einer URL.
      *
-     * @param deviceName
+     * @param {string} deviceName Der zu bereinigende Gerätename
+     * @returns {string}          Bereinigter Name oder 'NA' wenn leer
      */
     sanitizeZ2MDeviceName(deviceName) {
-        if (!deviceName) {return 'NA';}
-        const deviceNameString = deviceName.replace(/:|\s|\//g, '-');
+        if (!deviceName) { return 'NA'; }
         // eslint-disable-next-line no-control-regex
-        return deviceNameString.replace(/\u0000/g, '');
+        return deviceName.replace(/:|\s|\//g, '-').replace(/\u0000/g, '');
     }
 
     /**
-     * @param device
-     * @param ext
+     * Erstellt die zigbee2mqtt.io-Bild-URL für ein Gerät.
+     *
+     * @param {object} device Das Geräteobjekt aus dem Z2M-Payload
+     * @param {string} ext    Dateiendung ('jpg' oder 'png')
+     * @returns {string|undefined} Die Bild-URL oder undefined wenn kein Modell vorhanden
      */
     _buildZ2mImageUrl(device, ext) {
         if (device && device.definition && device.definition.model) {
@@ -49,14 +56,20 @@ class ImageController {
     }
 
     /**
-     * @param device
+     * Gibt die JPG-Bild-URL des Geräts auf zigbee2mqtt.io zurück.
+     *
+     * @param {object} device Das Geräteobjekt
+     * @returns {string|undefined} Die JPG-URL oder undefined
      */
     getZ2mDeviceImageModelJPG(device) {
         return this._buildZ2mImageUrl(device, 'jpg');
     }
 
     /**
-     * @param device
+     * Gibt die PNG-Bild-URL des Geräts auf zigbee2mqtt.io zurück.
+     *
+     * @param {object} device Das Geräteobjekt
+     * @returns {string|undefined} Die PNG-URL oder undefined
      */
     getZ2mDeviceImageModelPNG(device) {
         return this._buildZ2mImageUrl(device, 'png');
@@ -64,8 +77,10 @@ class ImageController {
 
 
     /**
+     * Gibt die SLS-Bild-URL des Geräts (alternative Quelle) zurück.
      *
-     * @param device
+     * @param {object} device Das Geräteobjekt mit model_id-Feld
+     * @returns {string|undefined} Die Bild-URL oder undefined
      */
     getSlsDeviceImage(device) {
         if (device && device.model_id) {
@@ -73,11 +88,15 @@ class ImageController {
             // eslint-disable-next-line no-control-regex
             return icoString.replace(/\u0000/g, '');
         }
+        return undefined;
     }
 
     /**
+     * Lädt das Icon eines Geräts herunter (falls noch nicht gecacht), skaliert es
+     * auf die konfigurierte Größe und gibt es als Base64-Data-URL zurück.
      *
-     * @param device
+     * @param {object} device Das Geräteobjekt aus dem Z2M-bridge/devices-Payload
+     * @returns {Promise<string>} Base64-kodiertes Icon als Data-URL oder ''
      */
     async getDeviceIcon(device) {
         if (!this.adapter.config.useDeviceIcons) {
@@ -111,7 +130,7 @@ class ImageController {
                         break;
                     }
                 } catch (ex) {
-                    //  check next pic
+                    this.adapter.log.debug(`Icon download failed for ${iconUrl}: ${ex && ex.message ? ex.message : ex}`);
                 }
             }
         }
@@ -122,6 +141,10 @@ class ImageController {
         }
 
         const icon = await this.adapter.readFileAsync(this.adapter.namespace, iconFileName);
+        if (!icon || !icon.file) {
+            this.adapter.log.warn(`Failed to read icon file: ${iconFileName}`);
+            return '';
+        }
         const origIconMeta = await sharp(icon.file).metadata();
         if (
             (origIconMeta.height && origIconMeta.height > imageSize) ||
@@ -143,9 +166,12 @@ class ImageController {
 
         return `data:image/png;base64,${icon.file.toString('base64')}`;
     }
+
     /**
+     * Extrahiert den Dateinamen (mit Erweiterung) aus einer URL.
      *
-     * @param url
+     * @param {string} url Die vollständige URL
+     * @returns {string}   Dateiname (z.B. "TRADFRI_bulb.jpg")
      */
     getFileNameWithExtension(url) {
         const path = new URL(url).pathname;
@@ -155,26 +181,30 @@ class ImageController {
     }
 
     /**
+     * Lädt ein Icon von der angegebenen URL herunter und speichert es im ioBroker-Dateisystem.
      *
-     * @param adapter
-     * @param url
-     * @param namespace
+     * @param {object} adapter   Die ioBroker-Adapter-Instanz
+     * @param {string} url       Download-URL des Icons
+     * @param {string} namespace ioBroker-Namespace (z.B. "zigbee2mqtt.0")
+     * @returns {Promise<boolean>} true bei Erfolg, false bei Fehler
      */
     async downloadIcon(adapter, url, namespace) {
         try {
-            const res = await axios.get(url, { responseType: 'arraybuffer' });
+            const res = await axios.get(url, { responseType: 'arraybuffer', timeout: 10000 });
             await adapter.writeFileAsync(namespace, this.getFileNameWithExtension(url), res.data);
             return true;
         } catch (ex) {
-            //adapter.log.warn(ex);
             return false;
         }
     }
+
     /**
+     * Prüft welcher lokale Icon-Dateiname bereits im ioBroker-Dateisystem existiert.
      *
-     * @param z2mIconFileNameJPG
-     * @param z2mIconFileNamePNG
-     * @param slsIconFileName
+     * @param {string} z2mIconFileNameJPG JPG-Dateiname (Z2M-Format)
+     * @param {string} z2mIconFileNamePNG PNG-Dateiname (Z2M-Format)
+     * @param {string} slsIconFileName    PNG-Dateiname (SLS-Format)
+     * @returns {Promise<string|null>}    Erster gefundener Dateiname oder null
      */
     async getExistingIconFileName(z2mIconFileNameJPG, z2mIconFileNamePNG, slsIconFileName) {
         if (await this.adapter.fileExistsAsync(this.adapter.namespace, z2mIconFileNameJPG)) {

package/lib/messages.js

@@ -1,9 +1,10 @@
 /**
+ * Gibt die aktuelle Adapter-Konfiguration formatiert als Log-Block aus.
  *
- * @param config
- * @param log
+ * @param {object} config Die Adapter-Konfiguration (this.config)
+ * @param {object} log    Das ioBroker-Log-Objekt (this.log)
  */
-async function adapterInfo(config, log) {
+function adapterInfo(config, log) {
     if (!config || !log) {
         return;
     }
@@ -12,23 +13,23 @@ async function adapterInfo(config, log) {
     log.info(`|| Zigbee2MQTT Frontend Server: ${config.webUIServer}`);
     log.info(`|| Zigbee2MQTT Frontend Port: ${config.webUIPort}`);
     log.info(`|| Zigbee2MQTT Connection Type: ${config.connectionType}`);
-    if (config.connectionType == 'ws') {
+    if (config.connectionType === 'ws') {
         log.info(`|| Zigbee2MQTT Websocket Scheme: ${config.wsScheme}`);
         log.info(`|| Zigbee2MQTT Websocket Server: ${config.wsServerIP}`);
         log.info(`|| Zigbee2MQTT Websocket Port: ${config.wsServerPort}`);
         log.info(`|| Zigbee2MQTT Websocket Auth-Token: ${config.wsTokenEnabled ? 'use' : 'unused'}`);
         log.info(`|| Zigbee2MQTT Websocket Dummy MQTT-Server: ${config.dummyMqtt ? 'activated' : 'deactivated'}`);
-        if (config.dummyMqtt == true) {
+        if (config.dummyMqtt === true) {
             log.info(`|| Zigbee2MQTT Dummy MQTT IP-Bind: ${config.mqttServerIPBind}`);
             log.info(`|| Zigbee2MQTT Dummy MQTT Port: ${config.mqttServerPort}`);
         }
-    } else if (config.connectionType == 'exmqtt') {
-        log.info(`|| Zigbee2MQTT Externanl MQTT Server: ${config.externalMqttServerIP}`);
-        log.info(`|| Zigbee2MQTT Externanl MQTT Port: ${config.externalMqttServerPort}`);
+    } else if (config.connectionType === 'exmqtt') {
+        log.info(`|| Zigbee2MQTT External MQTT Server: ${config.externalMqttServerIP}`);
+        log.info(`|| Zigbee2MQTT External MQTT Port: ${config.externalMqttServerPort}`);
         log.info(
-            `|| Zigbee2MQTT Externanl MQTT Credentials: ${config.externalMqttServerCredentials ? 'use' : 'unused'}`
+            `|| Zigbee2MQTT External MQTT Credentials: ${config.externalMqttServerCredentials ? 'use' : 'unused'}`
         );
-    } else if (config.connectionType == 'intmqtt') {
+    } else if (config.connectionType === 'intmqtt') {
         log.info(`|| Zigbee2MQTT Internal MQTT IP-Bind: ${config.mqttServerIPBind}`);
         log.info(`|| Zigbee2MQTT Internal MQTT Port: ${config.mqttServerPort}`);
     }
@@ -50,11 +51,12 @@ async function adapterInfo(config, log) {
 }
 
 /**
+ * Gibt die Zigbee2MQTT-Bridge-Informationen formatiert als Log-Block aus.
  *
- * @param payload
- * @param log
+ * @param {object} payload Der Payload des bridge/info-Topics
+ * @param {object} log     Das ioBroker-Log-Objekt (this.log)
  */
-async function zigbee2mqttInfo(payload, log) {
+function zigbee2mqttInfo(payload, log) {
     if (!payload || !log) {
         return;
     }

package/lib/mqttServerController.js

@@ -5,11 +5,14 @@ const { Aedes } = require('aedes');
 const net = require('node:net');
 
 /**
- *
+ * Verwaltet den internen oder Dummy-MQTT-Server (Aedes) für den Zigbee2MQTT-Adapter.
+ * Wird im intmqtt- und ws-Modus (dummyMqtt) verwendet.
  */
 class MqttServerController {
     /**
-     * @param adapter
+     * Erstellt eine neue MqttServerController-Instanz.
+     *
+     * @param {object} adapter Die ioBroker-Adapter-Instanz
      */
     constructor(adapter) {
         this.adapter     = adapter;
@@ -20,7 +23,7 @@ class MqttServerController {
     /**
      * Prüft ob Port und Bind-Adresse konfiguriert sind.
      *
-     * @returns {boolean}
+     * @returns {boolean} true wenn die Konfiguration vollständig ist, sonst false
      */
     _checkConfig() {
         if (!this.adapter.config.mqttServerPort || !this.adapter.config.mqttServerIPBind) {
@@ -31,9 +34,9 @@ class MqttServerController {
     }
 
     /**
-     * Hängt error- und close-Events an einen net.Server.
+     * Hängt error- und close-Event-Handler an den internen net.Server.
      *
-     * @param {string} label
+     * @param {string} label Bezeichnung des Servers für Log-Ausgaben (z.B. "MQTT-Server")
      */
     _attachServerEvents(label) {
         if (!this.mqttServer) {
@@ -48,7 +51,8 @@ class MqttServerController {
     }
 
     /**
-     * Startet den internen MQTT-Server mit Persistenz (aedes + nedb).
+     * Startet den internen MQTT-Server mit nedb-Persistenz (aedes + aedes-persistence-nedb).
+     * Wartet auf den erfolgreichen listen()-Aufruf bevor die Methode zurückkehrt.
      */
     async createMQTTServer() {
         if (!this._checkConfig()) {
@@ -90,7 +94,8 @@ class MqttServerController {
     }
 
     /**
-     * Startet einen Dummy-MQTT-Server ohne Persistenz (für WS-Modus).
+     * Startet einen Dummy-MQTT-Server ohne Persistenz.
+     * Wird im WebSocket-Modus (dummyMqtt=true) benötigt damit Z2M einen MQTT-Broker findet.
      */
     async createDummyMQTTServer() {
         if (!this._checkConfig()) {
@@ -121,7 +126,8 @@ class MqttServerController {
     }
 
     /**
-     * Schließt den MQTT-Server und den Aedes-Broker.
+     * Schließt den MQTT-Server und den Aedes-Broker sicher.
+     * Wird beim Adapter-Stop oder nach einem Fehler beim Start aufgerufen.
      */
     closeServer() {
         if (this.mqttServer) {

package/lib/nonGenericDevicesExtension.js

@@ -40,9 +40,8 @@ function getStateDefinition(model) {
     const stateDef = nonGenDevStatesDefs[model];
     if (stateDef) {
         return stateDef;
-    } 
-        return [];
-    
+    }
+    return [];
 }
 
 module.exports = {

package/lib/rgb.js

@@ -115,10 +115,15 @@ function cie_to_rgb(x, y, brightness) {
  * @returns {Array} Array that contains the CIE color values for x and y
  */
 function rgb_to_cie(red, green, blue) {
+    // Normalize RGB values from 0-255 to 0-1 before gamma correction
+    red   = red   / 255;
+    green = green / 255;
+    blue  = blue  / 255;
+
     // Apply a gamma correction to the RGB values, which makes the color more vivid and more the like the color displayed on the screen of your device
-    red = red > 0.04045 ? Math.pow((red + 0.055) / (1.0 + 0.055), 2.4) : red / 12.92;
+    red   = red   > 0.04045 ? Math.pow((red   + 0.055) / (1.0 + 0.055), 2.4) : red   / 12.92;
     green = green > 0.04045 ? Math.pow((green + 0.055) / (1.0 + 0.055), 2.4) : green / 12.92;
-    blue = blue > 0.04045 ? Math.pow((blue + 0.055) / (1.0 + 0.055), 2.4) : blue / 12.92;
+    blue  = blue  > 0.04045 ? Math.pow((blue  + 0.055) / (1.0 + 0.055), 2.4) : blue  / 12.92;
 
     // RGB values to XYZ using the Wide RGB D65 conversion formula
     const X = red * 0.664511 + green * 0.154324 + blue * 0.162028;
@@ -155,7 +160,9 @@ function hsvToRGB(h, s, v) {
     let g;
     let b;
     if (arguments.length === 1) {
-        (s = h.s), (v = h.v), (h = h.h);
+        s = h.s;
+        v = h.v;
+        h = h.h;
     }
     const i = Math.floor(h * 6);
     const f = h * 6 - i;
@@ -163,24 +170,13 @@ function hsvToRGB(h, s, v) {
     const q = v * (1 - f * s);
     const t = v * (1 - (1 - f) * s);
     switch (i % 6) {
-        case 0:
-            (r = v), (g = t), (b = p);
-            break;
-        case 1:
-            (r = q), (g = v), (b = p);
-            break;
-        case 2:
-            (r = p), (g = v), (b = t);
-            break;
-        case 3:
-            (r = p), (g = q), (b = v);
-            break;
-        case 4:
-            (r = t), (g = p), (b = v);
-            break;
-        case 5:
-            (r = v), (g = p), (b = q);
-            break;
+        case 0: r = v; g = t; b = p; break;
+        case 1: r = q; g = v; b = p; break;
+        case 2: r = p; g = v; b = t; break;
+        case 3: r = p; g = q; b = v; break;
+        case 4: r = t; g = p; b = v; break;
+        case 5: r = v; g = p; b = q; break;
+        default: r = 0; g = 0; b = 0; break;
     }
     return {
         r: Math.round(r * 255),
@@ -198,7 +194,9 @@ function hsvToRGB(h, s, v) {
  */
 function rgbToHSV(r, g, b, numeric) {
     if (arguments.length === 1) {
-        (g = r.g), (b = r.b), (r = r.r);
+        g = r.g;
+        b = r.b;
+        r = r.r;
     }
     const max = Math.max(r, g, b);
     const min = Math.min(r, g, b);
@@ -225,20 +223,18 @@ function rgbToHSV(r, g, b, numeric) {
             break;
     }
     if (numeric) {
-      return {
-
+        return {
             h: Math.round(h * 360),
             s: Math.round(s * 100),
             v: Math.round(v * 100),
         };
     }
-      return {
-    
+    return {
         h: (h * 360).toFixed(3),
         s: (s * 100).toFixed(3),
         v: (v * 100).toFixed(3),
-      };
-  }
+    };
+}
 
 /**
  *
@@ -281,20 +277,20 @@ function hsv_to_cie(h, s, v) {
 function rgb_to_rgbstring(element) {
     let col = '#';
     if (element && element.hasOwnProperty('r')) {
-col = col + element.r.toString(16).padStart(2, '0');
-} else {
-col = `${col  }00`;
-}
+        col += element.r.toString(16).padStart(2, '0');
+    } else {
+        col += '00';
+    }
     if (element && element.hasOwnProperty('g')) {
-col = col + element.g.toString(16).padStart(2, '0');
-} else {
-col = `${col  }00`;
-}
+        col += element.g.toString(16).padStart(2, '0');
+    } else {
+        col += '00';
+    }
     if (element && element.hasOwnProperty('b')) {
-col = col + element.b.toString(16).padStart(2, '0');
-} else {
-col = `${col  }00`;
-}
+        col += element.b.toString(16).padStart(2, '0');
+    } else {
+        col += '00';
+    }
     return col;
 }
 
@@ -306,30 +302,23 @@ col = `${col  }00`;
  */
 function hsbToRGB(h, s, b) {
     const br = Math.round(b * 2.55);
-    if (s == 0) {
+    if (s === 0) {
         return [br, br, br];
-    } 
-        const hue = h % 360;
-        const f = hue % 60;
-        const p = Math.round(b * (100 - s) * 0.0255);
-        const q = Math.round(b * (6000 - s * f) * 0.000425);
-        const t = Math.round(b * (6000 - s * (60 - f)) * 0.000425);
-        switch (Math.floor(hue / 60)) {
-            case 0:
-                return [br, t, p];
-            case 1:
-                return [q, br, p];
-            case 2:
-                return [p, br, t];
-            case 3:
-                return [p, q, br];
-            case 4:
-                return [t, p, br];
-            case 5:
-                return [br, p, q];
-        }
-    
-    return false;
+    }
+    const hue = h % 360;
+    const f = hue % 60;
+    const p = Math.round(b * (100 - s) * 0.0255);
+    const q = Math.round(b * (6000 - s * f) * 0.000425);
+    const t = Math.round(b * (6000 - s * (60 - f)) * 0.000425);
+    switch (Math.floor(hue / 60)) {
+        case 0: return [br, t, p];
+        case 1: return [q, br, p];
+        case 2: return [p, br, t];
+        case 3: return [p, q, br];
+        case 4: return [t, p, br];
+        case 5: return [br, p, q];
+    }
+    return [br, br, br]; // fallback – sollte nie erreicht werden
 }
 
 /**