node-red-contrib-ccu 4.5.2 → 4.6.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.6.0 (2026-10-22)
+
+### Added
+
+- **A device is created in Home Assistant in the room of its channels.** The
+  discovery config carries the room as the device's `suggested_area` (task
+  18). It did so before only when every channel of the device lay in one and
+  the same room: a device with channels in two rooms got no area, and on
+  openccu-lite, whose rooms can be nested and whose room list of a channel
+  names the parents too (`Küche`, `Erdgeschoss`), no device got one at all.
+  Now the area is the room shared by all channels of the device that lie in a
+  room, otherwise the room of the lowest-numbered channel that lies in one; a
+  channel in several rooms counts with its first (on openccu-lite the most
+  specific), and a room of the device itself comes first. The rooms are the
+  ReGaHSS's on a CCU and the system's metadata's on openccu-lite. New option
+  _Suggest the channel's room as the device's area_ on the node, on by
+  default. Home Assistant applies the suggestion only when it first creates
+  the device; a room changed later stays as assigned in Home Assistant.
+
+## 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,20 @@ 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.
+
+The device is created in the room of its channels: the discovery config carries it as the device's `suggested_area`
+(Home Assistant's areas are per device, the CCU's rooms per channel). The rule: the room shared by all channels of the
+device that lie in a room, otherwise the room of the lowest-numbered channel that lies in one; a channel in several
+rooms counts with its first - on openccu-lite, where rooms can be nested, with the most specific one - and a room of
+the device itself comes first. The rooms come from the ReGaHSS on a CCU and from the system's metadata on openccu-lite.
+Home Assistant applies the suggestion only when it first creates the device; a room changed later on the CCU stays as
+assigned in Home Assistant (change it there, or delete the device in Home Assistant and republish the discovery). The
+node's option _Suggest the channel's room as the device's area_ (on by default) switches it off.
+
 ## 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.html

@@ -7,6 +7,7 @@
             mqttNode: {value: '', required: true},
             prefix: {value: 'homeassistant'},
             generic: {value: true},
+            area: {value: true},
             devices: {value: {}},
         },
         inputs: 1,
@@ -267,6 +268,15 @@
             </label>
         </div>
     </div>
+    <div class="form-row">
+        <label for="node-input-area"></label>
+        <div style="width: 70%; display: inline-block; vertical-align: text-top;">
+            <label class="ccu-checkbox">
+                <input type="checkbox" id="node-input-area">
+                <span>Suggest the channel's room as the device's area</span>
+            </label>
+        </div>
+    </div>
 
     <div class="form-row">
         <b>Devices published to Home Assistant</b>

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 {
@@ -32,6 +37,7 @@ module.exports = function (RED) {
             this.mqttNodeId = config.mqttNode;
             this.prefix = String(config.prefix || 'homeassistant').replace(/\/+$/, '');
             this.generic = config.generic !== false;
+            this.area = config.area !== false;
             this.devices = config.devices || {};
             this.selected = Object.keys(this.devices).filter(
                 (a) => this.devices[a] && this.devices[a].enabled === true,
@@ -43,9 +49,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 +70,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 +86,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);
         }
 
@@ -193,6 +215,7 @@ module.exports = function (RED) {
                 origin: {name: pkg.name, sw: pkg.version, url: pkg.homepage},
                 jsonPayloads: mqtt.payloadOutput !== 'plain',
                 generic: this.generic,
+                area: this.area,
                 devices: ccu.metadata.devices,
                 selected: this.selected,
                 description: (iface, address) => {
@@ -207,7 +230,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 +241,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 +265,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

@@ -51,7 +51,9 @@ const BINARY_ONLY_CLASSES = new Set([
  * @property {string[]} selected device addresses to publish
  * @property {(iface: string, address: string) => object | undefined} description VALUES description of a channel
  * @property {(address: string) => string | undefined} channelName
- * @property {(address: string) => string[] | undefined} [rooms]
+ * @property {(address: string) => string[] | undefined} [rooms] the rooms of a channel (or device), the
+ *           most specific first where rooms are nested (openccu-lite)
+ * @property {boolean} [area] the room becomes the device's `suggested_area` (default true, task 18)
  * @property {(iface: string, address: string, datapoint: string) => string} statusTopicFor
  * @property {(iface: string, address: string, datapoint: string) => string} setTopicFor
  */
@@ -175,12 +177,47 @@ 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`
+ */
+
+/**
+ * The room Home Assistant is to suggest as the device's area (task 18). Home
+ * Assistant's area is per device, the CCU's rooms are per channel, so: a room
+ * every channel that lies in a room shares - the first one in the order of the
+ * lowest-numbered such channel - or, when they share none, the first room of
+ * the lowest-numbered channel that has one. A room of the device itself (an
+ * openccu-lite device may be in a room as a whole) comes first. Home Assistant
+ * applies `suggested_area` only when it creates the device; a room changed
+ * later stays as assigned in Home Assistant.
+ * @param {(address: string) => string[] | undefined} roomsOf
+ * @param {string} deviceAddress
+ * @param {Array<{ADDRESS: string}>} channels sorted by channel index
+ * @returns {string | undefined}
+ */
+function suggestedArea(roomsOf, deviceAddress, channels) {
+    const lists = [deviceAddress, ...channels.map((ch) => ch.ADDRESS)]
+        .map((address) => roomsOf(address))
+        .filter((rooms) => Array.isArray(rooms) && rooms.length > 0);
+    if (lists.length === 0) {
+        return undefined;
+    }
+
+    const [first, ...rest] = lists;
+    return first.find((room) => rest.every((rooms) => rooms.includes(room))) || first[0];
+}
+
 /**
  * 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) {
@@ -215,12 +252,7 @@ function deviceBlock(ctx, iface, device) {
         components[key] = e;
     };
 
-    const rooms = new Set();
-    for (const ch of channels) {
-        for (const r of roomsOf(ch.ADDRESS) || []) {
-            rooms.add(r);
-        }
-    }
+    const area = ctx.area === false ? undefined : suggestedArea(roomsOf, device.ADDRESS, channels);
 
     const maintenance = channels.find((ch) => ch.index === 0);
 
@@ -752,13 +784,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 {
@@ -768,10 +806,11 @@ function deviceBlock(ctx, iface, device) {
             mf: 'eQ-3',
             mdl: device.TYPE,
             sw: device.FIRMWARE ? String(device.FIRMWARE) : undefined,
-            sa: rooms.size === 1 ? [...rooms][0] : undefined,
+            sa: area,
         }),
         components,
         availability,
+        unreach,
     };
 }
 
@@ -807,11 +846,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 +870,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 = {
@@ -839,6 +883,7 @@ module.exports = {
     discoveryTopic,
     ifaceOf,
     resolveVirtualReceivers,
+    suggestedArea,
     deviceBlock,
     devicePayload,
     removalMessage,

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

@@ -16,8 +16,27 @@
     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>
+    <h3>Raum und Bereich</h3>
+    <p>Home Assistant ordnet Geräte Bereichen zu, die CCU Kanäle Räumen. Der Node schlägt Home Assistant den
+    Raum der Kanäle als Bereich des Geräts vor (<code>suggested_area</code>): den Raum, den alle Kanäle des
+    Geräts teilen, die in einem Raum liegen, sonst den Raum des Kanals mit der niedrigsten Nummer, der in
+    einem liegt. Liegt ein Kanal in mehreren Räumen, zählt der erste; auf openccu-lite, wo Räume verschachtelt
+    sein können, der speziellste (das Zimmer vor dem Stockwerk), und ein Raum des Geräts selbst geht vor. Die
+    Räume kommen auf einer CCU aus der ReGaHSS, auf openccu-lite aus den Metadaten des Systems.</p>
+    <p>Home Assistant übernimmt den Vorschlag nur, wenn es das Gerät neu anlegt. Ein später auf der CCU
+    geänderter Raum bleibt in Home Assistant, wie er dort zugeordnet ist: dort ändern, oder das Gerät in Home
+    Assistant löschen und die Discovery erneut veröffentlichen. Die Option <i>Raum als Bereich vorschlagen</i>
+    schaltet den Vorschlag ab.</p>
 </script>

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

@@ -16,8 +16,27 @@
     <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>
+    <h3>Room and area</h3>
+    <p>Home Assistant assigns devices to areas, the CCU assigns channels to rooms. The node suggests the
+    channels' room as the device's area (<code>suggested_area</code>): the room shared by all channels of
+    the device that lie in a room, otherwise the room of the lowest-numbered channel that lies in one. A
+    channel in several rooms counts with its first; on openccu-lite, where rooms can be nested, with the most
+    specific one (the room before the floor), and a room of the device itself comes first. The rooms come
+    from the ReGaHSS on a CCU and from the system's metadata on openccu-lite.</p>
+    <p>Home Assistant applies the suggestion only when it creates the device. A room changed later on the
+    CCU stays as assigned in Home Assistant: change it there, or delete the device in Home Assistant and
+    republish the discovery. The option <i>Suggest the channel's room as the device's area</i> switches the
+    suggestion off.</p>
 </script>

package/package.json

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