node-red-contrib-ccu 4.5.2 → 4.5.3

package/CHANGELOG.md

@@ -5,6 +5,27 @@ Notable changes to node-red-contrib-ccu. Format follows
 user-visible symptom and the cause, not the commit list (the release notes
 append commits automatically).
 
+## 4.5.3 (2026-10-05)
+
+### Fixed
+
+- **Home Assistant showed every entity of a device as "unavailable" for
+  good** (B-38, reported by mail). The discovery configs name the device's
+  `…:0/UNREACH` topic as its availability, and Home Assistant treats an
+  entity as unavailable until that topic delivers a value. Only `ccu-mqtt`
+  published UNREACH: when it changed, or once in its start-up burst of
+  cached values - which is off unless the node's _Cache_ option is ticked,
+  and lost when the MQTT broker is not connected yet at that moment (Node-RED's
+  `mqtt out` drops what it gets while disconnected). A device that never went
+  unreachable therefore never got a value on that topic, while its state
+  updates arrived normally. The `ccu-homeassistant` node now publishes each
+  device's current UNREACH itself, retained, right after the discovery
+  configs (asking the CCU for it) and every change after that; _republish
+  discovery_ sends it again. The example flow also wires Home Assistant's
+  birth message (`homeassistant/status`) to the node, so a Home Assistant
+  restart republishes discovery and availability; an `offline` there is
+  ignored.
+
 ## 4.5.2 (2026-10-02)
 
 ### Fixed

package/README.md

@@ -76,6 +76,11 @@ device with switch, light, cover, climate, binary_sensor, event, lock and sensor
 optionally be included as a disabled-by-default entity. Unticking a device removes it from Home Assistant on the
 next deploy.
 
+A device's availability in Home Assistant follows the `UNREACH` datapoint of its maintenance channel. The node
+publishes its current value (retained) right after the discovery configs and every change after that, so a device
+is available without ever having been unreachable. Any message on the node's input republishes both; the example
+wires Home Assistant's birth message (`homeassistant/status`) to it, so a Home Assistant restart gets them again.
+
 ## Dynamic configuration
 
 Most nodes can be reconfigured per message: put an object in `msg.config` and its

package/examples/home-assistant.json

@@ -81,6 +81,22 @@
     "y": 180,
     "wires": [["ccu-ha-example"]]
   },
+  {
+    "id": "mqtt-in-ha-status",
+    "type": "mqtt in",
+    "name": "homeassistant/status",
+    "topic": "homeassistant/status",
+    "qos": "0",
+    "datatype": "utf8",
+    "broker": "mqtt-broker-example",
+    "nl": false,
+    "rap": true,
+    "rh": 0,
+    "inputs": 0,
+    "x": 170,
+    "y": 220,
+    "wires": [["ccu-ha-example"]]
+  },
   {
     "id": "comment-ha",
     "type": "comment",

package/nodes/ccu-homeassistant.js

@@ -15,8 +15,13 @@ const READY_ATTEMPTS = 60;
  * Companion to a ccu-mqtt node: reuses its topic templates and payload format, so
  * the discovery configs point at the topics ccu-mqtt already publishes/consumes.
  * The node itself only emits (a) the retained discovery configs — wire its output
- * to the same mqtt-out node as the ccu-mqtt node — and (b) the aggregate PRESS
- * event Home Assistant's event entities need.
+ * to the same mqtt-out node as the ccu-mqtt node —, (b) the aggregate PRESS
+ * event Home Assistant's event entities need and (c) the devices' UNREACH on the
+ * availability topics the configs name (B-38): Home Assistant shows an entity
+ * "unavailable" until its availability topic delivers a value, and ccu-mqtt
+ * publishes UNREACH only when it changes or in its start-up cache burst (which
+ * is off by default and lost when the broker is not connected yet), so a device
+ * that never went unreachable would stay unavailable for good.
  */
 module.exports = function (RED) {
     class CcuHomeAssistantNode {
@@ -43,9 +48,18 @@ module.exports = function (RED) {
 
             this.ccu.register(this);
 
+            /** datapointName → {iface, channel, datapoint, topic} of the published availability topics */
+            this.availability = new Map();
+            /** datapointName → the UNREACH value last published on its topic */
+            this.availabilitySent = new Map();
+
             this.on('input', (message, send, done) => {
-                // any message republishes the discovery configs
-                this.publish(true);
+                // any message republishes the discovery configs - except Home Assistant's
+                // own "offline" (its last will) when <prefix>/status is wired in
+                if (!this.isHomeAssistantOffline(message)) {
+                    this.publish(true);
+                }
+
                 if (done) {
                     done();
                 }
@@ -55,6 +69,11 @@ module.exports = function (RED) {
                 this.event(message);
             });
 
+            // B-38: UNREACH from the ReGa's values (cache) and every later event
+            this.idUnreachSubscription = this.ccu.subscribe({cache: true, datapoint: 'UNREACH'}, (message) => {
+                this.unreach(message);
+            });
+
             this.on('close', (done) => {
                 this._destructor(done);
             });
@@ -66,8 +85,10 @@ module.exports = function (RED) {
 
         _destructor(done) {
             this.trace('ccu-homeassistant close');
+            this.closed = true;
             clearTimeout(this.readyTimer);
             this.ccu.unsubscribe(this.idEventSubscription);
+            this.ccu.unsubscribe(this.idUnreachSubscription);
             this.ccu.deregister(this, done);
         }
 
@@ -207,7 +228,7 @@ module.exports = function (RED) {
                     topicReplace(mqtt.topicInputSetValue, this.topicMessage(iface, address, dp)),
             };
 
-            const {messages, missing, empty} = discoveryMessages(ctx);
+            const {messages, availability, missing, empty} = discoveryMessages(ctx);
 
             for (const address of this.removed) {
                 const {topic, payload} = removalMessage(this.prefix, address);
@@ -218,6 +239,8 @@ module.exports = function (RED) {
                 this.send({topic, payload, retain: true});
             }
 
+            this.publishAvailability(availability);
+
             if (missing.length > 0) {
                 this.warn('selected devices not found on the CCU: ' + missing.join(', '));
             }
@@ -240,6 +263,88 @@ module.exports = function (RED) {
             });
         }
 
+        /** Home Assistant's last will on `<prefix>/status` - not a reason to republish */
+        isHomeAssistantOffline(message) {
+            return (
+                message &&
+                message.topic === this.prefix + '/status' &&
+                String(message.payload).trim().toLowerCase() !== 'online'
+            );
+        }
+
+        /**
+         * B-38: put the current UNREACH of every published device on its availability
+         * topic, retained, right after the discovery configs - from the values the
+         * connection holds when they are certain, and from the interface process
+         * (getValue, deferred by the connection until the interface is up) in any case.
+         * @param {Array<{iface: string, channel: string, datapoint: string, topic: string}>} availability
+         */
+        publishAvailability(availability) {
+            this.availability = new Map();
+            this.availabilitySent = new Map();
+            for (const source of availability) {
+                const datapointName = source.iface + '.' + source.channel + '.' + source.datapoint;
+                this.availability.set(datapointName, source);
+
+                const cached = this.ccu.values && this.ccu.values[datapointName];
+                if (cached && !cached.uncertain && typeof cached.value === 'boolean') {
+                    this.sendAvailability(datapointName, cached.value, cached);
+                }
+
+                const known = this.availability;
+                this.ccu
+                    .methodCall(source.iface, 'getValue', [source.channel, source.datapoint], {quiet: true})
+                    .then((value) => {
+                        // a republish in between started a new round
+                        if (this.availability === known) {
+                            this.sendAvailability(datapointName, Boolean(value));
+                        }
+                    })
+                    .catch((error) => {
+                        this.debug('getValue ' + datapointName + ': ' + error.message);
+                    });
+            }
+        }
+
+        /** an UNREACH message of the connection (cache or event) */
+        unreach(message) {
+            if (message && this.availability.has(message.datapointName) && typeof message.value === 'boolean') {
+                this.sendAvailability(message.datapointName, message.value, message);
+            }
+        }
+
+        /**
+         * One retained UNREACH on an availability topic, in the ccu-mqtt node's payload
+         * format; skipped when the topic already carries that value from this node.
+         * @param {string} datapointName
+         * @param {boolean} value
+         * @param {object} [message] the connection's message for the datapoint, if there is one
+         */
+        sendAvailability(datapointName, value, message) {
+            const source = this.availability.get(datapointName);
+            if (this.closed || !source || this.availabilitySent.get(datapointName) === value) {
+                return;
+            }
+
+            const mqtt = this.mqttNodeId && RED.nodes.getNode(this.mqttNodeId);
+            if (!mqtt || typeof mqtt.output !== 'function') {
+                return;
+            }
+
+            const now = Date.now();
+            const out = {
+                ts: now,
+                lc: now,
+                ...message,
+                ...this.topicMessage(source.iface, source.channel, source.datapoint),
+                payload: value,
+                value,
+            };
+            delete out.topic;
+            this.availabilitySent.set(datapointName, value);
+            this.send({topic: source.topic, payload: mqtt.output(out), retain: true});
+        }
+
         /** key presses: Home Assistant's event entity wants one topic per key → <channel>/PRESS */
         event(message) {
             if (!message.datapoint || !message.datapoint.startsWith('PRESS_') || !message.payload) {

package/nodes/lib/hadiscovery.js

@@ -175,12 +175,21 @@ function resolveVirtualReceivers(channels) {
     }
 }
 
+/**
+ * The datapoint behind a device's availability topic (the maintenance channel's UNREACH).
+ * @typedef {object} Availability
+ * @property {string} iface
+ * @property {string} channel address of the maintenance channel (…:0)
+ * @property {string} datapoint always UNREACH
+ * @property {string} topic the status topic the discovery config names in `avty`
+ */
+
 /**
  * Builds the discovery block of one device.
  * @param {DiscoveryContext} ctx
  * @param {string} iface
  * @param {object} device device metadata (ADDRESS, TYPE, CHILDREN, FIRMWARE)
- * @returns {{id: string, device: object, components: object, availability: object[]} | null}
+ * @returns {{id: string, device: object, components: object, availability: object[], unreach?: Availability} | null}
  *          null when the device yields no entity
  */
 function deviceBlock(ctx, iface, device) {
@@ -752,13 +761,19 @@ function deviceBlock(ctx, iface, device) {
         return null;
     }
 
-    // availability: the device's UNREACH (retained by ccu-mqtt) — there is no
-    // bridge "connected" topic in the ccu-mqtt topic scheme
+    // availability: the device's UNREACH — there is no bridge "connected" topic in the
+    // ccu-mqtt topic scheme. HA shows every entity "unavailable" until this topic delivers
+    // a value, and ccu-mqtt publishes UNREACH only on a change or in its start-up cache
+    // burst, so the ccu-homeassistant node publishes the current value itself (B-38):
+    // `unreach` tells it which datapoint and topic.
     // (an entry of the availability list takes `val_tpl`; `avty_tpl` is only valid at
     // the top level next to `avty_t` — HA rejects the whole device payload otherwise)
     const availability = [];
+    let unreach;
     if (maintenance && maintenance.description.UNREACH) {
-        availability.push({t: st(iface, maintenance.ADDRESS, 'UNREACH'), val_tpl: t.bool('offline', 'online')});
+        const topic = st(iface, maintenance.ADDRESS, 'UNREACH');
+        availability.push({t: topic, val_tpl: t.bool('offline', 'online')});
+        unreach = {iface, channel: maintenance.ADDRESS, datapoint: 'UNREACH', topic};
     }
 
     return {
@@ -772,6 +787,7 @@ function deviceBlock(ctx, iface, device) {
         }),
         components,
         availability,
+        unreach,
     };
 }
 
@@ -807,11 +823,13 @@ function removalMessage(prefix, address) {
 /**
  * Discovery messages for the selected devices.
  * @param {DiscoveryContext} ctx
- * @returns {{messages: Array<{topic: string, payload: object}>, missing: string[], empty: string[]}}
+ * @returns {{messages: Array<{topic: string, payload: object}>, availability: Availability[], missing: string[], empty: string[]}}
+ *          availability: the UNREACH datapoints the configs use as availability (B-38);
  *          missing: selected addresses not found in the metadata; empty: devices without entities
  */
 function discoveryMessages(ctx) {
     const messages = [];
+    const availability = [];
     const missing = [];
     const empty = [];
     for (const address of ctx.selected || []) {
@@ -829,9 +847,12 @@ function discoveryMessages(ctx) {
         }
 
         messages.push(devicePayload(ctx, block));
+        if (block.unreach) {
+            availability.push(block.unreach);
+        }
     }
 
-    return {messages, missing, empty};
+    return {messages, availability, missing, empty};
 }
 
 module.exports = {

package/nodes/locales/de/ccu-homeassistant.html

@@ -16,8 +16,16 @@
     Option <i>weitere Datenpunkte</i> werden alle übrigen Datenpunkte als standardmäßig deaktivierte
     Entitäten mitgeliefert.</p>
     <h3>Eingang</h3>
-    <p>Jede eingehende Nachricht veröffentlicht die Discovery-Konfigurationen erneut.</p>
+    <p>Jede eingehende Nachricht veröffentlicht die Discovery-Konfigurationen und die Verfügbarkeit
+    erneut. Wer einen <b>mqtt in</b>-Node auf <code>homeassistant/status</code> (bzw.
+    <code>&lt;Präfix&gt;/status</code>) anschließt, bekommt beides nach jedem Neustart von Home Assistant
+    neu; dessen <code>offline</code> auf diesem Topic wird ignoriert.</p>
     <h3>Voraussetzungen</h3>
-    <p>Home Assistant ≥ 2024.11 (gerätebasierte Discovery). Die Verfügbarkeit der Geräte wird aus dem
-    UNREACH-Datenpunkt des Wartungskanals abgeleitet.</p>
+    <p>Home Assistant ≥ 2024.11 (gerätebasierte Discovery).</p>
+    <h3>Verfügbarkeit</h3>
+    <p>Die Verfügbarkeit der Geräte wird aus dem UNREACH-Datenpunkt des Wartungskanals abgeleitet
+    (<code>…:0/UNREACH</code>). Home Assistant zeigt alle Entitäten eines Geräts als „nicht verfügbar“,
+    bis auf diesem Topic ein Wert ankommt. Deshalb veröffentlicht der Node direkt nach den
+    Discovery-Konfigurationen den aktuellen UNREACH-Wert jedes Geräts (retained), fragt ihn dazu bei der
+    CCU ab und sendet jede Änderung. Ein Gerät, das nie unerreichbar war, ist so trotzdem verfügbar.</p>
 </script>

package/nodes/locales/en-US/ccu-homeassistant.html

@@ -16,8 +16,16 @@
     <i>other datapoints</i> option every remaining datapoint is included as an entity that is
     disabled by default.</p>
     <h3>Input</h3>
-    <p>Any incoming message republishes the discovery configs.</p>
+    <p>Any incoming message republishes the discovery configs and the availability. Wire an
+    <b>mqtt in</b> node on <code>homeassistant/status</code> (or <code>&lt;prefix&gt;/status</code>) to
+    the input to get both again after every Home Assistant restart; its <code>offline</code> on that
+    topic is ignored.</p>
     <h3>Requirements</h3>
-    <p>Home Assistant ≥ 2024.11 (device-based discovery). Device availability is derived from the
-    UNREACH datapoint of the maintenance channel.</p>
+    <p>Home Assistant ≥ 2024.11 (device-based discovery).</p>
+    <h3>Availability</h3>
+    <p>Device availability is derived from the UNREACH datapoint of the maintenance channel
+    (<code>…:0/UNREACH</code>). Home Assistant shows every entity of a device as "unavailable" until
+    a value arrives on that topic. So right after the discovery configs the node publishes each
+    device's current UNREACH (retained), asking the CCU for it, and sends every change. A device that
+    was never unreachable is available all the same.</p>
 </script>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-ccu",
-  "version": "4.5.2",
+  "version": "4.5.3",
   "license": "MIT",
   "main": "none",
   "keywords": [