node-red-contrib-ccu 4.5.3 → 4.6.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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

package/README.md

@@ -81,6 +81,15 @@ publishes its current value (retained) right after the discovery configs and eve
 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/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

@@ -37,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,
@@ -214,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) => {

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
  */
@@ -184,6 +186,32 @@ function resolveVirtualReceivers(channels) {
  * @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
@@ -224,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);
 
@@ -783,7 +806,7 @@ 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,
@@ -860,6 +883,7 @@ module.exports = {
     discoveryTopic,
     ifaceOf,
     resolveVirtualReceivers,
+    suggestedArea,
     deviceBlock,
     devicePayload,
     removalMessage,

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

@@ -28,4 +28,15 @@
     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

@@ -28,4 +28,15 @@
     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.3",
+  "version": "4.6.0",
   "license": "MIT",
   "main": "none",
   "keywords": [