iobroker.faikout 0.0.5

package/lib/verbrauch.js

@@ -0,0 +1,214 @@
+'use strict';
+
+/*
+ * Verbrauchsrechnung aus den Lebensdauer-Zaehlern der Anlage.
+ *
+ * Die Module liefern nur monoton steigende Gesamtzaehler in Wh (energy, energyheat,
+ * energycool). Verbrauch je Stunde und Tag entsteht erst durch Differenzbildung - und dabei
+ * gibt es vier Faelle, die man nicht naiv behandeln darf:
+ *
+ *   1. Der Zaehler springt zurueck (Modul-Neustart, Firmware-Reset). Eine negative Differenz
+ *      darf NICHT als riesiger Verbrauch gebucht werden; stattdessen neu basieren.
+ *   2. Der Adapter war Stunden offline. Die aufgelaufene Differenz gehoert nicht komplett in
+ *      die letzte Stunde - die uebersprungenen Stunden werden als Luecke (null) vermerkt.
+ *   3. Der Stundenwechsel passiert auch ohne eintreffende Nachricht. Deshalb muss der Aufrufer
+ *      zusaetzlich zyklisch anstossen (siehe pruefen()).
+ *   4. Nach einem Adapter-Neustart muessen die Basiswerte noch da sein, sonst faengt jede
+ *      Zaehlung wieder bei null an. Der Zustand gehoert deshalb persistiert.
+ *
+ * Dieses Modul ist bewusst frei von ioBroker-Abhaengigkeiten: rein Zustand rein, Zustand raus.
+ */
+
+/** Wie viele abgeschlossene Stunden der Ringpuffer behaelt. */
+const RING_STUNDEN = 48;
+/* Zwei Monate Tageswerte reichen fuer jede Monatsansicht, auch am Monatsersten. */
+const RING_TAGE = 62;
+/* Zwei Jahre Monatswerte - so laesst sich das laufende Jahr mit dem Vorjahr vergleichen. */
+const RING_MONATE = 24;
+
+/** Wh -> kWh, auf 3 Stellen. */
+function kwh(wh) {
+    return Math.round(wh) / 1000;
+}
+
+/** Stundenschluessel wie 2026-08-17T14 (lokale Zeit, denn Tageswechsel ist lokal gemeint). */
+function stundeVon(d) {
+    const p = n => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}`;
+}
+
+function monatVon(d) {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+}
+
+function tagVon(d) {
+    return stundeVon(d).slice(0, 10);
+}
+
+/** Wie viele volle Stunden liegen zwischen zwei Stundenschluesseln? */
+function stundenDazwischen(a, b) {
+    const zeit = s => new Date(
+        Number(s.slice(0, 4)), Number(s.slice(5, 7)) - 1, Number(s.slice(8, 10)), Number(s.slice(11, 13))
+    ).getTime();
+    return Math.round((zeit(b) - zeit(a)) / 3600000);
+}
+
+/** Leerer Anfangszustand eines Zaehlers. */
+function neuerStand() {
+    return {
+        letzterWert: null,   // zuletzt gesehener Gesamtzaehler in Wh
+        basisStunde: null,   // Zaehlerstand zu Beginn der laufenden Stunde
+        basisTag: null,      // Zaehlerstand zu Beginn des laufenden Tages
+        stunde: null,        // Schluessel der laufenden Stunde
+        tag: null,           // Schluessel des laufenden Tages
+        letzteStunde: null,  // kWh der zuletzt abgeschlossenen Stunde
+        gestern: null,       // kWh des Vortages
+        monat: null,         // Schluessel des laufenden Monats
+        basisMonat: null,    // Zaehlerstand zu Monatsbeginn
+        letzterMonat: null,  // kWh des Vormonats
+        ring: [],            // [{ stunde, kwh }] - kwh null = Luecke
+        ringTage: [],        // [{ tag, kwh }] - Grundlage der Monatsansicht
+        ringMonate: [],      // [{ monat, kwh }] - Grundlage der Jahresansicht
+    };
+}
+
+/**
+ * Verarbeitet einen neuen Zaehlerstand.
+ *
+ * @param {object|null} stand  bisheriger Zustand (aus der Persistenz) oder null
+ * @param {number} wert        aktueller Gesamtzaehler in Wh
+ * @param {Date} [jetzt]       Zeitpunkt (fuer Tests setzbar)
+ * @returns {{stand: object, werte: object, hinweise: string[]}}
+ */
+function verarbeiten(stand, wert, jetzt = new Date()) {
+    const hinweise = [];
+    // Ueber neuerStand() zusammenfuehren, nicht nur uebernehmen: ein Zustand aus einer aelteren
+    // Fassung kennt spaeter ergaenzte Felder nicht, und ein fehlender Ring liess das Update von
+    // 0.0.1 auf 0.0.2 bei jedem Zaehlerwert mit "reading 'push'" auflaufen.
+    const s = stand
+        ? {
+            ...neuerStand(),
+            ...stand,
+            ring: (stand.ring || []).slice(),
+            ringTage: (stand.ringTage || []).slice(),
+            ringMonate: (stand.ringMonate || []).slice(),
+        }
+        : neuerStand();
+    const stunde = stundeVon(jetzt);
+    const tag = tagVon(jetzt);
+    const monat = monatVon(jetzt);
+
+    if (typeof wert !== 'number' || !isFinite(wert)) {
+        return { stand: s, werte: ausgabe(s, s.letzterWert), hinweise };
+    }
+
+    // --- Erster Wert ueberhaupt -------------------------------------------------
+    if (s.letzterWert === null || s.basisStunde === null || s.basisTag === null) {
+        s.letzterWert = wert;
+        s.basisStunde = wert;
+        s.basisTag = wert;
+        s.basisMonat = wert;
+        s.stunde = stunde;
+        s.tag = tag;
+        s.monat = monat;
+        return { stand: s, werte: ausgabe(s, wert), hinweise };
+    }
+
+    // --- Zaehler zurueckgesprungen ----------------------------------------------
+    // Kommt beim Neustart des Moduls vor. Der Verbrauch dazwischen ist nicht mehr
+    // ermittelbar; alles neu basieren, damit kein Fantasiewert entsteht.
+    if (wert < s.letzterWert) {
+        hinweise.push(`Zählerstand zurückgesprungen (${s.letzterWert} -> ${wert} Wh) - Zählung neu begonnen`);
+        s.letzterWert = wert;
+        s.basisStunde = wert;
+        s.basisTag = wert;
+        s.basisMonat = wert;
+        s.stunde = stunde;
+        s.tag = tag;
+        s.monat = monat;
+        return { stand: s, werte: ausgabe(s, wert), hinweise };
+    }
+
+    // --- Stundenwechsel ---------------------------------------------------------
+    if (s.stunde !== stunde) {
+        const luecke = stundenDazwischen(s.stunde, stunde) - 1; // uebersprungene volle Stunden
+        s.letzteStunde = kwh(s.letzterWert - s.basisStunde);
+        s.ring.push({ stunde: s.stunde, kwh: s.letzteStunde });
+        if (luecke > 0) {
+            // Der Adapter war offline. Was in dieser Zeit verbraucht wurde, laesst sich nicht
+            // auf die einzelnen Stunden aufteilen - als Luecke kennzeichnen statt zu erfinden.
+            hinweise.push(`${luecke} Stunde(n) ohne Daten - als Lücke vermerkt`);
+            for (let i = 1; i <= luecke; i++) s.ring.push({ stunde: null, kwh: null });
+        }
+        if (s.ring.length > RING_STUNDEN) s.ring = s.ring.slice(-RING_STUNDEN);
+        s.basisStunde = s.letzterWert;
+        s.stunde = stunde;
+    }
+
+    // --- Tageswechsel -----------------------------------------------------------
+    if (s.tag !== tag) {
+        s.gestern = kwh(s.letzterWert - s.basisTag);
+        s.ringTage.push({ tag: s.tag, kwh: s.gestern });
+        if (s.ringTage.length > RING_TAGE) s.ringTage = s.ringTage.slice(-RING_TAGE);
+        s.basisTag = s.letzterWert;
+        s.tag = tag;
+    }
+
+    // --- Monatswechsel ----------------------------------------------------------
+    // Bewusst nach dem Tageswechsel: der letzte Tag des alten Monats gehoert noch dorthin.
+    if (s.monat !== monat) {
+        if (s.monat === null || s.basisMonat === null) {
+            // Erster Monat, den dieser Zaehler sieht - er hat keinen Vorgaenger. Ohne diese
+            // Ausnahme wurde bei einem Zustand aus 0.0.1 (kannte noch keinen Monat) der volle
+            // Zaehlerstand als Vormonatsverbrauch gebucht: 3783 kWh statt der echten Differenz.
+            s.basisMonat = s.letzterWert;
+            s.monat = monat;
+        } else {
+            s.letzterMonat = kwh(s.letzterWert - s.basisMonat);
+            s.ringMonate.push({ monat: s.monat, kwh: s.letzterMonat });
+            if (s.ringMonate.length > RING_MONATE) s.ringMonate = s.ringMonate.slice(-RING_MONATE);
+            s.basisMonat = s.letzterWert;
+            s.monat = monat;
+        }
+    }
+
+    s.letzterWert = wert;
+    return { stand: s, werte: ausgabe(s, wert), hinweise };
+}
+
+/**
+ * Stossen ohne neuen Zaehlerstand - fuer den Timer auf die volle Stunde. Meldet einen
+ * Stunden- bzw. Tageswechsel auch dann, wenn gerade keine Nachricht hereinkam.
+ */
+function pruefen(stand, jetzt = new Date()) {
+    if (!stand || stand.letzterWert === null) return { stand, werte: null, hinweise: [] };
+    if (stand.stunde === stundeVon(jetzt) && stand.tag === tagVon(jetzt)
+        && stand.monat === monatVon(jetzt)) {
+        return { stand, werte: null, hinweise: [] };
+    }
+    return verarbeiten(stand, stand.letzterWert, jetzt);
+}
+
+function ausgabe(s, wert) {
+    return {
+        gesamt: wert === null ? null : kwh(wert),
+        stunde: s.basisStunde === null || wert === null ? null : kwh(wert - s.basisStunde),
+        letzteStunde: s.letzteStunde,
+        heute: s.basisTag === null || wert === null ? null : kwh(wert - s.basisTag),
+        gestern: s.gestern,
+        dieserMonat: s.basisMonat === null || wert === null ? null : kwh(wert - s.basisMonat),
+        letzterMonat: s.letzterMonat,
+        ring: s.ring,
+        // Der laufende Tag bzw. Monat steht noch nicht im Ring - fuer die Anzeige gehoert er
+        // aber ans Ende, sonst fehlt in der Monatsansicht immer der heutige Balken.
+        ringTage: s.ringTage.concat(
+            s.tag && wert !== null ? [{ tag: s.tag, kwh: kwh(wert - s.basisTag) }] : []),
+        ringMonate: s.ringMonate.concat(
+            s.monat && wert !== null ? [{ monat: s.monat, kwh: kwh(wert - s.basisMonat) }] : []),
+    };
+}
+
+module.exports = {
+    verarbeiten, pruefen, neuerStand, stundeVon, tagVon, monatVon, kwh,
+    RING_STUNDEN, RING_TAGE, RING_MONATE,
+};

package/main.js

@@ -0,0 +1,451 @@
+'use strict';
+
+/*
+ * ioBroker.faikout
+ * Bindet Daikin-Klimaanlagen mit faikout-Modul rein ueber MQTT an - mit eigenem Broker.
+ */
+
+const utils = require('@iobroker/adapter-core');
+const { FaikoutBroker } = require('./lib/broker');
+const felder = require('./lib/fields');
+const verbrauch = require('./lib/verbrauch');
+
+/** Topics, die der Adapter auswertet. Alles andere wird still verworfen. */
+const BEKANNTE_ARTEN = new Set(['state', 'info', 'error', 'event']);
+
+/**
+ * Die drei Lebensdauer-Zaehler und ihr Zweig im Objektbaum. Die Gesamtzaehler bleiben
+ * erhalten (status.*), zusaetzlich entstehen daraus die Verbrauchswerte (verbrauch.*).
+ */
+const ZAEHLER = [
+    { feld: 'energy', zweig: 'gesamt', name: { en: 'Total', de: 'Gesamt' } },
+    { feld: 'energyheat', zweig: 'heizen', name: { en: 'Heating', de: 'Heizen' } },
+    { feld: 'energycool', zweig: 'kuehlen', name: { en: 'Cooling', de: 'Kühlen' } },
+];
+
+/** Datenpunkte je Zaehlerzweig. */
+const VERBRAUCH_FELDER = [
+    { id: 'stunde', name: { en: 'Current hour', de: 'Laufende Stunde' } },
+    { id: 'letzteStunde', name: { en: 'Last full hour', de: 'Letzte volle Stunde' } },
+    { id: 'heute', name: { en: 'Today', de: 'Heute' } },
+    { id: 'gestern', name: { en: 'Yesterday', de: 'Gestern' } },
+    { id: 'dieserMonat', name: { en: 'This month', de: 'Dieser Monat' } },
+    { id: 'letzterMonat', name: { en: 'Last month', de: 'Letzter Monat' } },
+];
+
+/**
+ * Verlaufsreihen als JSON. Sie tragen die Diagramme im VIS-Baustein und werden hier gefuehrt,
+ * damit der Adapter ohne Fremdskript auskommt - andernfalls blieben Monats- und Jahresansicht
+ * bei jedem leer, der nichts weiter einrichtet.
+ */
+const VERBRAUCH_REIHEN = [
+    { id: 'stundenJson', quelle: 'ring',
+      name: { en: 'Last 48 hours (JSON)', de: 'Letzte 48 Stunden (JSON)' } },
+    { id: 'tageJson', quelle: 'ringTage',
+      name: { en: 'Last 62 days (JSON)', de: 'Letzte 62 Tage (JSON)' } },
+    { id: 'monateJson', quelle: 'ringMonate',
+      name: { en: 'Last 24 months (JSON)', de: 'Letzte 24 Monate (JSON)' } },
+];
+
+class Faikout extends utils.Adapter {
+    constructor(options) {
+        super({ ...options, name: 'faikout' });
+
+        /**
+         * Geraete, die sich gemeldet haben.
+         * Schluessel ist die ioBroker-taugliche ID, Wert enthaelt den ECHTEN Geraetenamen -
+         * der enthaelt bei diesen Modulen ein Leerzeichen ("Wohnzimmer AC"), waehrend die
+         * Objekt-ID einen Unterstrich braucht. Kommandos muessen den echten Namen treffen,
+         * sonst hoert das Geraet nicht zu.
+         * @type {Map<string, {name:string, angelegt:Set<string>}>}
+         */
+        this.geraete = new Map();
+
+        this.broker = null;
+        this.stopping = false;
+        this.stundenTimer = null;
+
+        this.on('ready', this.onReady.bind(this));
+        this.on('stateChange', this.onStateChange.bind(this));
+        this.on('unload', this.onUnload.bind(this));
+    }
+
+    // ---------------------------------------------------------------- Start
+
+    async onReady() {
+        await this.setState('info.connection', { val: false, ack: true });
+
+        const port = Number(this.config.port) || 1888;
+        this.broker = new FaikoutBroker({
+            port,
+            user: this.config.user,
+            pass: this.config.pass,
+            log: this.log,
+            onMessage: (topic, payload) => this.onMqtt(topic, payload),
+            onClient: () => this.verbindungPruefen(),
+        });
+
+        try {
+            await this.broker.start();
+        } catch (e) {
+            this.log.error(`MQTT-Broker konnte nicht starten: ${e.message}`);
+            return;
+        }
+
+        this.log.info(
+            `Bereit. Die faikout-Module müssen als MQTT-Host <IP des ioBroker>:${port} eingetragen sein.`,
+        );
+        this.subscribeStates('*.control.*');
+        this.stundenTaktStarten();
+    }
+
+    /**
+     * Weckt die Verbrauchsrechnung zur vollen Stunde.
+     *
+     * Noetig, weil die Module nur zyklisch senden (Einstellung "reporting", ab Werk 60 s):
+     * ohne eigenen Takt wuerde ein Stundenwechsel erst mit der naechsten Nachricht bemerkt
+     * und die Stunde bekaeme Verbrauch aus der falschen Periode zugerechnet.
+     */
+    stundenTaktStarten() {
+        const jetzt = new Date();
+        const naechste = new Date(jetzt);
+        naechste.setHours(jetzt.getHours() + 1, 0, 5, 0); // 5 s nach der vollen Stunde
+        this.stundenTimer = this.setTimeout(() => {
+            this.stundenwechsel().catch(e => this.log.warn(`Stundenwechsel: ${e.message}`));
+            this.stundenTaktStarten();
+        }, naechste - jetzt);
+    }
+
+    async stundenwechsel() {
+        for (const [id, g] of this.geraete) {
+            for (const z of ZAEHLER) {
+                const ergebnis = verbrauch.pruefen(g.zaehler[z.feld], new Date());
+                if (!ergebnis.werte) continue;
+                g.zaehler[z.feld] = ergebnis.stand;
+                ergebnis.hinweise.forEach(h => this.log.info(`${g.name} ${z.zweig}: ${h}`));
+                await this.verbrauchSchreiben(id, g, z, ergebnis.werte);
+            }
+            await this.zaehlerstandSichern(id, g);
+        }
+    }
+
+    verbindungPruefen() {
+        // Verbunden heisst hier: mindestens ein faikout-Modul haengt am Broker.
+        this.setState('info.connection', { val: this.geraete.size > 0, ack: true });
+    }
+
+    // ---------------------------------------------------------------- MQTT hinein
+
+    /**
+     * Zerlegt ein Topic in Art, Geraet und Unterpfad.
+     * `state/Wohnzimmer AC` -> {art:'state', geraet:'Wohnzimmer AC', unter:''}
+     * `info/Wohnzimmer AC/upgrade` -> {art:'info', geraet:'Wohnzimmer AC', unter:'upgrade'}
+     */
+    topicZerlegen(topic) {
+        const teile = topic.split('/');
+        if (teile.length < 2) return null;
+        const [art, geraet, ...rest] = teile;
+        if (!BEKANNTE_ARTEN.has(art)) return null;
+        return { art, geraet, unter: rest.join('/') };
+    }
+
+    onMqtt(topic, payload) {
+        const text = payload ? payload.toString('utf8') : '';
+        if (!text) return;
+
+        // Die Module veroeffentlichen ihre Faehigkeiten selbst als Home-Assistant-Discovery.
+        // Daraus kommen Bereich und Schrittweite der Solltemperatur - die unterscheiden sich
+        // je Anlage (eine nimmt halbe Grad, die andere nur ganze, Einstellung "ha1c").
+        if (topic.startsWith('homeassistant/climate/') && topic.endsWith('/config')) {
+            this.klimaConfig(text).catch(e => this.log.debug(`HA-Config: ${e.message}`));
+            return;
+        }
+
+        const t = this.topicZerlegen(topic);
+        if (!t) return; // command/…, Faikout/… - nicht ausgewertet
+
+        if (t.art === 'error') {
+            this.log.warn(`${t.geraet}: ${text}`);
+            return;
+        }
+
+        let daten;
+        try {
+            daten = JSON.parse(text);
+        } catch {
+            this.log.debug(`Kein JSON auf "${topic}": ${text.slice(0, 80)}`);
+            return;
+        }
+        if (!daten || typeof daten !== 'object') return;
+
+        // state/<Name> ist die Hauptmeldung im Klartext. state/<Name>/status liefert dasselbe
+        // im nativen Format (mode "C" statt "cool") - das waere doppelt und wird uebergangen.
+        if (t.art === 'state' && !t.unter) {
+            this.werteUebernehmen(t.geraet, daten).catch(e => this.log.warn(`${t.geraet}: ${e.message}`));
+        } else if (t.art === 'info' && t.unter === 'upgrade') {
+            this.werteUebernehmen(t.geraet, { version: daten.version, build: daten.build }).catch(() => {});
+        }
+    }
+
+    /**
+     * Wertet die HA-Discovery einer Klimaeinheit aus und uebernimmt Bereich und Schrittweite
+     * der Solltemperatur ins Objekt `control.target`.
+     */
+    async klimaConfig(text) {
+        const c = JSON.parse(text);
+        // Der Geraetename steckt im Verfuegbarkeits-Topic: "state/Wohnzimmer AC".
+        const geraetName = String(c.avty_t || '').replace(/^state\//, '');
+        if (!geraetName) return;
+
+        const id = this.geraetId(geraetName);
+        const grenzen = {
+            min: Number(c.min_temp),
+            max: Number(c.max_temp),
+            step: Number(c.temp_step),
+        };
+        if (!isFinite(grenzen.min) || !isFinite(grenzen.max) || !isFinite(grenzen.step)) return;
+
+        const g = this.geraete.get(id);
+        if (g && g.grenzen && g.grenzen.step === grenzen.step &&
+            g.grenzen.min === grenzen.min && g.grenzen.max === grenzen.max) {
+            return; // unveraendert - die Discovery wird regelmaessig wiederholt
+        }
+        if (g) g.grenzen = grenzen;
+
+        const stateId = `${id}.control.target`;
+        const vorhanden = await this.getObjectAsync(stateId);
+        if (vorhanden) {
+            await this.extendObject(stateId, { common: grenzen });
+            this.log.info(`${geraetName}: Sollwertbereich ${grenzen.min}–${grenzen.max} °C in ${grenzen.step}er-Schritten übernommen.`);
+        }
+    }
+
+    /** Legt fehlende Objekte an und schreibt die Werte. */
+    async werteUebernehmen(geraetName, daten) {
+        const id = this.geraetId(geraetName);
+        let g = this.geraete.get(id);
+        if (!g) {
+            // Frueheren Stand uebernehmen, falls es das Geraet aus einem vorherigen Lauf gibt -
+            // vor allem den Merker, ob die Luftfeuchte echt ist.
+            const alt = await this.getObjectAsync(id);
+            g = {
+                name: geraetName,
+                angelegt: new Set(),
+                feuchteEcht: !!(alt && alt.native && alt.native.feuchteEcht),
+                // Die Zaehlerstaende muessen den Adapter-Neustart ueberleben, sonst faengt
+                // jede Zaehlung wieder bei null an.
+                zaehler: (alt && alt.native && alt.native.zaehler) || {},
+                grenzen: (alt && alt.native && alt.native.grenzen) || null,
+            };
+            this.geraete.set(id, g);
+            await this.extendObject(id, {
+                type: 'device',
+                common: { name: geraetName },
+                native: { faikoutName: geraetName },
+            });
+            this.log.info(`Gerät erkannt: "${geraetName}" -> ${this.namespace}.${id}`);
+            this.verbindungPruefen();
+        }
+        // Der Name kann sich aendern, wenn der Hostname im Modul umgestellt wird.
+        g.name = geraetName;
+
+        for (const [feld, wert] of Object.entries(daten)) {
+            if (wert === null || wert === undefined) continue;
+            if (felder.UEBERSPRINGEN.has(feld)) continue;
+            if (typeof wert === 'object') continue; // verschachteltes (ble) - eigener Zweig, spaeter
+
+            // Anlagen ohne Feuchtesensor melden dauerhaft 50 - das ist ein Platzhalter, kein
+            // Messwert. Erst wenn einmal etwas anderes kam, gibt es wirklich einen Sensor.
+            if (feld === 'hum') {
+                const urteil = felder.feuchteBewerten(wert, g.feuchteEcht);
+                if (urteil.echtAbJetzt && !g.feuchteEcht) {
+                    g.feuchteEcht = true;
+                    await this.extendObject(id, { native: { feuchteEcht: true } });
+                    this.log.info(`${geraetName}: Luftfeuchte-Sensor erkannt (${wert} %) - Datenpunkt wird ab jetzt geführt.`);
+                }
+                if (!urteil.nehmen) continue;
+            }
+
+            const def = felder.beschreibe(feld, wert);
+            const stateId = `${id}.${def.kanal}.${felder.objektId(feld)}`;
+
+            if (!g.angelegt.has(stateId)) {
+                await this.objektAnlegen(id, def, feld, stateId);
+                g.angelegt.add(stateId);
+            }
+            await this.setState(stateId, { val: felder.umrechnen(def, wert), ack: true });
+        }
+
+        await this.zaehlerVerarbeiten(id, g, daten);
+    }
+
+    /** Bildet aus den Lebensdauer-Zaehlern die Stunden- und Tagesverbraeuche. */
+    async zaehlerVerarbeiten(id, g, daten) {
+        let veraendert = false;
+        for (const z of ZAEHLER) {
+            const roh = daten[z.feld];
+            if (typeof roh !== 'number') continue;
+            const ergebnis = verbrauch.verarbeiten(g.zaehler[z.feld] || null, roh, new Date());
+            g.zaehler[z.feld] = ergebnis.stand;
+            veraendert = true;
+            ergebnis.hinweise.forEach(h => this.log.info(`${g.name} ${z.zweig}: ${h}`));
+            await this.verbrauchSchreiben(id, g, z, ergebnis.werte);
+        }
+        if (veraendert) await this.zaehlerstandSichern(id, g);
+    }
+
+    async verbrauchSchreiben(id, g, z, werte) {
+        const basis = `${id}.verbrauch.${z.zweig}`;
+        if (!g.angelegt.has(basis)) {
+            await this.extendObject(`${id}.verbrauch`, {
+                type: 'channel',
+                common: { name: { en: 'Consumption', de: 'Verbrauch' } },
+                native: {},
+            });
+            await this.extendObject(basis, { type: 'channel', common: { name: z.name }, native: {} });
+            for (const f of VERBRAUCH_FELDER) {
+                await this.zaehlerObjekt(`${basis}.${f.id}`, f.name, 'kWh', 'value.energy.consumed');
+            }
+            for (const r of VERBRAUCH_REIHEN) {
+                await this.extendObject(`${basis}.${r.id}`, {
+                    type: 'state',
+                    common: { name: r.name, type: 'string', role: 'json', read: true, write: false },
+                    native: {},
+                });
+            }
+            g.angelegt.add(basis);
+        }
+
+        for (const f of VERBRAUCH_FELDER) {
+            const wert = werte[f.id];
+            if (wert === null || wert === undefined) continue;
+            await this.setState(`${basis}.${f.id}`, { val: wert, ack: true });
+        }
+        for (const r of VERBRAUCH_REIHEN) {
+            await this.setState(`${basis}.${r.id}`, {
+                val: JSON.stringify(werte[r.quelle] || []), ack: true,
+            });
+        }
+    }
+
+    /**
+     * Legt einen Verbrauchs-Datenpunkt an und meldet ihn - wenn gewuenscht - gleich beim
+     * History-Adapter zur Aufzeichnung an. Das erspart es, jeden Punkt von Hand im Admin
+     * einzuschalten.
+     */
+    async zaehlerObjekt(stateId, name, unit, role) {
+        const common = { name, type: 'number', role, unit, read: true, write: false };
+        const instanz = (this.config.historyInstanz || '').trim();
+        if (this.config.historyAnmelden && instanz) {
+            common.custom = {
+                [instanz]: { enabled: true, changesOnly: false, debounce: 0, retention: 0 },
+            };
+        }
+        await this.extendObject(stateId, { type: 'state', common, native: {} });
+    }
+
+    async zaehlerstandSichern(id, g) {
+        await this.extendObject(id, { native: { zaehler: g.zaehler } });
+    }
+
+    async objektAnlegen(geraetId, def, feld, stateId) {
+        await this.extendObject(`${geraetId}.${def.kanal}`, {
+            type: 'channel',
+            common: { name: this.kanalName(def.kanal) },
+            native: {},
+        });
+        const common = {
+            name: def.name,
+            type: def.type,
+            role: def.role,
+            read: true,
+            write: !!def.w,
+        };
+        if (def.unit) common.unit = def.unit;
+        if (def.states) common.states = def.states;
+        if (def.min !== undefined) common.min = def.min;
+        if (def.max !== undefined) common.max = def.max;
+        if (def.step !== undefined) common.step = def.step;
+
+        await this.extendObject(stateId, { type: 'state', common, native: { feld } });
+        if (def.unbekannt) {
+            this.log.info(`Unbekanntes Feld "${feld}" angelegt (${def.type}) - bitte melden, damit es sauber beschrieben wird.`);
+        }
+    }
+
+    kanalName(kanal) {
+        return {
+            control: { en: 'Control', de: 'Steuerung' },
+            status: { en: 'Readings', de: 'Messwerte' },
+            info: { en: 'Device info', de: 'Geräteinfo' },
+        }[kanal] || kanal;
+    }
+
+    /** Objekttaugliche ID aus dem Geraetenamen - Leerzeichen und Sonderzeichen raus. */
+    geraetId(name) {
+        return name.replace(/[\s.\][*,;'"`<>\\?]+/g, '_');
+    }
+
+    // ---------------------------------------------------------------- MQTT hinaus
+
+    async onStateChange(id, state) {
+        if (!state || state.ack) return; // nur eigene Befehle, nicht die eigenen Rueckmeldungen
+
+        const obj = await this.getObjectAsync(id);
+        if (!obj || !obj.common || !obj.common.write) return;
+
+        // faikout.0.<GeraetId>.control.<feld>
+        const teile = id.split('.');
+        const geraetId = teile[2];
+        const feld = (obj.native && obj.native.feld) || teile[teile.length - 1];
+        const g = this.geraete.get(geraetId);
+        if (!g) {
+            this.log.warn(`Befehl für unbekanntes Gerät ${geraetId} verworfen.`);
+            return;
+        }
+
+        // Manche Felder heissen beim Schreiben anders als beim Lesen: Der Sollwert kommt als
+        // `target` herein, das Kommandotopic dafuer heisst aber `temp`.
+        const def = felder.FELDER[feld];
+        const suffix = (def && def.cmd) || feld;
+
+        // Der ECHTE Geraetename gehoert ins Topic, nicht die bereinigte Objekt-ID.
+        const topic = `command/${g.name}/${suffix}`;
+        const nutzlast = this.nutzlast(feld, state.val);
+        const ok = await this.broker.publish(topic, nutzlast);
+        if (ok) {
+            this.log.debug(`-> ${topic} = ${nutzlast}`);
+            // Das Modul meldet seinen Zustand zyklisch (Einstellung "reporting", ab Werk 60 s)
+            // und nicht sofort nach dem Befehl. Der Wert wird deshalb erst mit der naechsten
+            // Statusmeldung bestaetigt - hier bewusst kein vorschnelles ack.
+        }
+    }
+
+    /** Wandelt einen ioBroker-Wert in die Nutzlast, die das Modul erwartet. */
+    nutzlast(feld, wert) {
+        if (typeof wert === 'boolean') return wert ? 'true' : 'false';
+        return String(wert);
+    }
+
+    // ---------------------------------------------------------------- Ende
+
+    async onUnload(callback) {
+        this.stopping = true;
+        try {
+            if (this.stundenTimer) this.clearTimeout(this.stundenTimer);
+            // Zaehlerstaende sichern, damit nach dem Neustart weitergezaehlt wird.
+            for (const [id, g] of this.geraete) await this.zaehlerstandSichern(id, g);
+            if (this.broker) await this.broker.stop();
+            await this.setState('info.connection', { val: false, ack: true });
+        } catch {
+            // beim Herunterfahren nicht weiter stoeren
+        }
+        callback();
+    }
+}
+
+if (require.main !== module) {
+    module.exports = options => new Faikout(options);
+} else {
+    new Faikout();
+}