node-red-contrib-ccu 4.1.0 → 4.2.0

package/nodes/lib/haroles.js

@@ -0,0 +1,193 @@
+/* Semantic roles of channels and the Home Assistant facts of datapoints.
+   Ported from hm2mqtt.js lib/roles.js (same author) for B-16.
+
+   hm2mqtt derives the role from the CONTROL hint eQ-3 puts on every VALUES
+   parameter. In the paramset cache shipped with this package (and therefore
+   in the persisted cache of existing installs) only about half of the VALUES
+   descriptions carry CONTROL fields — the older contributed user dumps were
+   stripped of them — so here the channel TYPE is the primary key and CONTROL
+   only refines where the description has it. Pure functions and tables, no I/O. */
+
+/** CONTROL hint of a channel's primary datapoint → role; checked in this order */
+const ROLE_BY_CONTROL = [
+    ['LOCK.STATE', 'lock'],
+    ['HEATING_CONTROL_HMIP.SETPOINT', 'climate_hmip'],
+    ['HEATING_CONTROL.SETPOINT', 'climate_hm'],
+    ['BLIND.LEVEL', 'cover'],
+    ['BLIND_VIRTUAL_RECEIVER.LEVEL', 'cover'],
+    ['SHUTTER_VIRTUAL_RECEIVER.LEVEL', 'cover'],
+    ['BLIND_TRANSMITTER.LEVEL', 'cover_state'],
+    ['SHUTTER_TRANSMITTER.LEVEL', 'cover_state'],
+    ['DIMMER.LEVEL', 'dimmer'],
+    ['DIMMER_REAL.LEVEL', 'dimmer_state'],
+    ['SWITCH.STATE', 'switch'],
+    ['SWITCH_TRANSMITTER.STATE', 'switch_state'],
+    ['DANGER.STATE', 'smoke'],
+    ['DOOR_SENSOR.STATE', 'contact'],
+    ['RHS.STATE', 'rotary_handle'],
+    ['MOTIONDETECTOR_TRANSCEIVER.MOTION_DETECTION_STATE', 'motion'],
+    ['POWERMETER.POWER', 'energy'],
+    ['POWERMETER_PSM.POWER', 'energy'],
+    ['WEATHER_TRANSMIT.ACTUAL_TEMPERATURE', 'weather'],
+    ['BUTTON.SHORT', 'key'],
+    ['BUTTON_NO_FUNCTION.SHORT', 'key'],
+];
+
+/** channel type → role (HM classic, HmIP and the CCU's own channels) */
+const ROLE_BY_TYPE = {
+    MAINTENANCE: 'maintenance',
+
+    // HM classic actuators
+    SWITCH: 'switch',
+    DIMMER: 'dimmer',
+    VIRTUAL_DIMMER: 'dimmer',
+    BLIND: 'cover',
+    KEYMATIC: 'lock',
+
+    // HmIP actuators: one *_TRANSMITTER (state) followed by *_VIRTUAL_RECEIVER channels (control)
+    SWITCH_VIRTUAL_RECEIVER: 'switch',
+    SWITCH_TRANSMITTER: 'switch_state',
+    DIMMER_VIRTUAL_RECEIVER: 'dimmer',
+    DIMMER_TRANSMITTER: 'dimmer_state',
+    BLIND_VIRTUAL_RECEIVER: 'cover',
+    SHUTTER_VIRTUAL_RECEIVER: 'cover',
+    BLIND_TRANSMITTER: 'cover_state',
+    SHUTTER_TRANSMITTER: 'cover_state',
+
+    // thermostats
+    HEATING_CLIMATECONTROL_TRANSCEIVER: 'climate_hmip',
+    CLIMATECONTROL_RT_TRANSCEIVER: 'climate_hm',
+    THERMALCONTROL_TRANSMIT: 'climate_hm',
+
+    // sensors
+    SHUTTER_CONTACT: 'contact',
+    SHUTTER_CONTACT_TRANSCEIVER: 'contact',
+    MULTI_MODE_INPUT_TRANSMITTER: 'contact',
+    TILT_SENSOR: 'contact',
+    ROTARY_HANDLE_SENSOR: 'rotary_handle',
+    ROTARY_HANDLE_TRANSCEIVER: 'rotary_handle',
+    MOTION_DETECTOR: 'motion',
+    MOTIONDETECTOR_TRANSCEIVER: 'motion',
+    PRESENCEDETECTOR_TRANSCEIVER: 'presence',
+    WEATHER: 'weather',
+    WEATHER_TRANSMIT: 'weather',
+    WATERDETECTIONSENSOR: 'water',
+    WATER_DETECTION_TRANSMITTER: 'water',
+    SMOKE_DETECTOR: 'smoke',
+    SMOKE_DETECTOR_TEAM: 'smoke',
+    SMOKE_DETECTOR_TEAM_V2: 'smoke',
+    POWERMETER: 'energy',
+    ENERGIE_METER_TRANSMITTER: 'energy',
+
+    // keys
+    KEY: 'key',
+    VIRTUAL_KEY: 'key',
+    KEY_TRANSCEIVER: 'key',
+    CENTRAL_KEY: 'key',
+};
+
+/**
+ * @param {string} channelType
+ * @param {object} [description] VALUES paramset description of the channel
+ * @returns {string | null}
+ */
+function channelRole(channelType, description) {
+    if (ROLE_BY_TYPE[channelType] === 'maintenance') {
+        return 'maintenance';
+    }
+
+    if (description) {
+        const controls = new Set(Object.values(description).map((d) => d && d.CONTROL));
+        for (const [control, role] of ROLE_BY_CONTROL) {
+            if (controls.has(control)) {
+                return role;
+            }
+        }
+    }
+
+    return ROLE_BY_TYPE[channelType] || null;
+}
+
+/** units as the interface processes send them → Home Assistant */
+function haUnit(unit) {
+    if (!unit || unit === '""') {
+        return undefined;
+    }
+
+    const u = String(unit).replace(/�|°/g, '°');
+    return (
+        {
+            '100%': '%',
+            '% rF': '%',
+            Lux: 'lx',
+            degree: '°',
+            '°': '°',
+            min: 'min',
+            s: 's',
+            mA: 'mA',
+        }[u] || u
+    );
+}
+
+/** `100%` values are 0..1 on the wire */
+function isFraction(description) {
+    return Boolean(description && description.UNIT === '100%');
+}
+
+/**
+ * Home Assistant facts of a datapoint by name: device class, state class, unit override,
+ * entity category, enabled by default. Anything not listed is a plain sensor / binary_sensor,
+ * disabled by default.
+ */
+const PARAMETERS = {
+    ACTUAL_TEMPERATURE: {dev_cla: 'temperature', stat_cla: 'measurement', unit: '°C', enabled: true},
+    TEMPERATURE: {dev_cla: 'temperature', stat_cla: 'measurement', unit: '°C', enabled: true},
+    SET_POINT_TEMPERATURE: {dev_cla: 'temperature', unit: '°C'},
+    SET_TEMPERATURE: {dev_cla: 'temperature', unit: '°C'},
+    HUMIDITY: {dev_cla: 'humidity', stat_cla: 'measurement', unit: '%', enabled: true},
+    ACTUAL_HUMIDITY: {dev_cla: 'humidity', stat_cla: 'measurement', unit: '%', enabled: true},
+    ILLUMINATION: {dev_cla: 'illuminance', stat_cla: 'measurement', unit: 'lx', enabled: true},
+    CURRENT_ILLUMINATION: {dev_cla: 'illuminance', stat_cla: 'measurement', unit: 'lx'},
+    AVERAGE_ILLUMINATION: {dev_cla: 'illuminance', stat_cla: 'measurement', unit: 'lx'},
+    BRIGHTNESS: {stat_cla: 'measurement', enabled: true},
+    POWER: {dev_cla: 'power', stat_cla: 'measurement', unit: 'W', enabled: true},
+    CURRENT: {dev_cla: 'current', stat_cla: 'measurement', unit: 'mA', enabled: true},
+    VOLTAGE: {dev_cla: 'voltage', stat_cla: 'measurement', unit: 'V', enabled: true},
+    FREQUENCY: {dev_cla: 'frequency', stat_cla: 'measurement', unit: 'Hz'},
+    ENERGY_COUNTER: {dev_cla: 'energy', stat_cla: 'total_increasing', unit: 'Wh', enabled: true},
+    RAIN_COUNTER: {dev_cla: 'precipitation', stat_cla: 'total_increasing', unit: 'mm', enabled: true},
+    RAINING: {dev_cla: 'moisture', enabled: true},
+    WIND_SPEED: {dev_cla: 'wind_speed', stat_cla: 'measurement', unit: 'km/h', enabled: true},
+    WIND_DIRECTION: {stat_cla: 'measurement', unit: '°', enabled: true},
+    WIND_DIR: {stat_cla: 'measurement', unit: '°', enabled: true},
+    SUNSHINEDURATION: {stat_cla: 'total_increasing', enabled: true},
+    AIR_PRESSURE: {dev_cla: 'atmospheric_pressure', stat_cla: 'measurement', unit: 'hPa', enabled: true},
+    VALVE_STATE: {stat_cla: 'measurement', unit: '%', enabled: true},
+    LEVEL: {stat_cla: 'measurement', unit: '%'},
+    BOOST_STATE: {unit: 'min'},
+    LOW_BAT: {dev_cla: 'battery', ent_cat: 'diagnostic', enabled: true},
+    LOWBAT: {dev_cla: 'battery', ent_cat: 'diagnostic', enabled: true},
+    UNREACH: {dev_cla: 'connectivity', ent_cat: 'diagnostic', inverted: true},
+    STICKY_UNREACH: {dev_cla: 'problem', ent_cat: 'diagnostic'},
+    CONFIG_PENDING: {ent_cat: 'diagnostic'},
+    UPDATE_PENDING: {dev_cla: 'update', ent_cat: 'diagnostic'},
+    DUTY_CYCLE: {dev_cla: 'problem', ent_cat: 'diagnostic'},
+    DUTYCYCLE: {dev_cla: 'problem', ent_cat: 'diagnostic'},
+    SABOTAGE: {dev_cla: 'tamper', ent_cat: 'diagnostic'},
+    ERROR_SABOTAGE: {dev_cla: 'tamper', ent_cat: 'diagnostic'},
+    RSSI_DEVICE: {dev_cla: 'signal_strength', stat_cla: 'measurement', unit: 'dBm', ent_cat: 'diagnostic'},
+    RSSI_PEER: {dev_cla: 'signal_strength', stat_cla: 'measurement', unit: 'dBm', ent_cat: 'diagnostic'},
+    OPERATING_VOLTAGE: {dev_cla: 'voltage', stat_cla: 'measurement', unit: 'V', ent_cat: 'diagnostic'},
+    ERROR_CODE: {ent_cat: 'diagnostic'},
+    WORKING: {dev_cla: 'running'},
+    PROCESS: {dev_cla: 'running'},
+    MOTION: {dev_cla: 'motion', enabled: true},
+    PRESENCE_DETECTION_STATE: {dev_cla: 'occupancy', enabled: true},
+    ALARMSTATE: {dev_cla: 'safety', enabled: true},
+    MOISTURE_DETECTED: {dev_cla: 'moisture', enabled: true},
+    WATERLEVEL_DETECTED: {dev_cla: 'moisture', enabled: true},
+    ON_TIME: {ent_cat: 'config', unit: 's'},
+    RAMP_TIME: {ent_cat: 'config', unit: 's'},
+};
+
+module.exports = {ROLE_BY_CONTROL, ROLE_BY_TYPE, channelRole, haUnit, isFraction, PARAMETERS};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-ccu",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "license": "MIT",
   "main": "none",
   "keywords": [
@@ -99,6 +99,7 @@
       "ccu-get-value": "nodes/ccu-get-value.js",
       "ccu-switch": "nodes/ccu-switch.js",
       "ccu-hm2mqtt": "nodes/ccu-mqtt.js",
+      "ccu-homeassistant": "nodes/ccu-homeassistant.js",
       "ccu-alexa": "nodes/ccu-alexa.js"
     }
   },

package/roadmap-archive/B-16.md

@@ -0,0 +1,31 @@
+# B-16 — ccu-homeassistant: Home Assistant MQTT auto-discovery node
+
+**✅ done 2026-09-04** (released as 4.2.0) — user request 2026-09-04.
+
+New node `ccu-homeassistant`: publishes device-based Home Assistant MQTT
+discovery configs (HA ≥ 2024.11) for a checkbox-selected set of devices.
+Companion to a ccu-mqtt node whose topic templates and payload format it
+reuses, so state and commands keep flowing through ccu-mqtt and the node
+itself only emits the retained discovery configs (plus the aggregate
+`<channel>/PRESS` item for event entities); unticked devices get an empty
+retained config. Mapping ported from hm2mqtt.js (`lib/haroles.js`,
+`lib/hadiscovery.js`, channel TYPE as primary role key because only about
+half of the shipped VALUES descriptions carry CONTROL hints). Editor: device
+table modeled on RedMatic-HomeKit (filter, check/uncheck all), ccu-mqtt
+select, prefix, generic-entities option; `type=devices` admin endpoint.
+Rode along: ccu-mqtt HA command words (OPEN/CLOSE/STOP/ON/OFF, HM
+`*-MODE`), empty-name topic fix, connection `deregister` fix.
+
+Verified 2026-09-04 on the two lab CCUs against Home Assistant 2026.9.0
+(docker) and she 1.51.1 (the author's dev instance on the test broker plus
+a private instance): DRS8 switches with round trip, DRI16 inputs + events,
+DRAP sensors, PDT light with brightness (plain payloads), WRC2 events,
+removal on untick, editor smoke test by the user. Three payload defects
+found only through the live test (availability-list `val_tpl`, switch
+`stat_on`/`stat_off`, binary-only device classes on sensors) — the first
+two are inherited from hm2mqtt.js / mqtt-interfaces-core and should be
+fixed upstream. Not covered by lab hardware: cover and climate payloads
+(unit tests only), real key presses. Known gaps (as upstream): RGBW lights,
+sirens, garage doors, sysvars/programs as entities.
+
+Original item: | B-16 | **New node `ccu-homeassistant`: Home Assistant MQTT auto-discovery for a checkbox-selected set of devices** (decided 2026-09-04: a dedicated node, not an option on ccu-mqtt). It is a companion to an existing ccu-mqtt node, not a replacement: its config references one ccu-mqtt node of the flow (select populated via `RED.nodes.eachNode`, type `ccu-mqtt`, same ccu-connection) and **reuses that node's configured topics** — `topicOutputEvent` as HA state topics, `topicInputSetValue` as command topics, `topicOutputSysvar` for sysvars later — plus its payload format (`payloadOutput` mqsh-basic/extended/plain → matching `value_template`, e.g. `{{ value_json.val }}`). State and commands keep flowing through ccu-mqtt; the new node only emits the retained discovery configs `{topic, payload, retain: true}` for the same downstream mqtt-out node (no broker connection of its own), republishes them on deploy/reconnect, and publishes empty retained configs for devices that were unchecked (removal from HA). **Device selection like RedMatic-HomeKit's `redmatic-homekit-homematic-devices` node**: the config dialog loads all devices of the connection from the `/ccu` admin endpoint into a table (checkbox · name · address · type, "enable all"/"disable all" buttons, filter box, optionally expandable per-channel rows), stored as a `devices` object keyed by address — but **opt-in**: nothing is checked, hence nothing published, until the user ticks a device. Mapping modeled on hm2mqtt.js [`lib/hadiscovery.js`](https://github.com/hobbyquaker/hm2mqtt.js/blob/master/lib/hadiscovery.js) (README section "Home Assistant"): one HA device per Homematic device, device-based discovery payloads `homeassistant/device/<id>/config` (HA ≥ 2024.11; prefix configurable), entities derived from the paramset descriptions' `CONTROL` hints — switch (SWITCH.STATE, HmIP virtual receivers), light (dimmers), cover (blind position/tilt/direction), climate (HM/HmIP thermostats, modes/presets), binary_sensor (contact/motion/presence/smoke/water), event (key press short/long), lock (KEYMATIC), sensor (energy, weather, maintenance) — port hm2mqtt's mapping table rather than re-deriving it. **Constraint found 2026-09-04 (corrected the same day):** only 290 of the 647 VALUES entries in the shipped `paramsets.json` carry `CONTROL` hints (the older contributed user dumps were stripped of them), and the persisted runtime cache of existing installs inherits that — so a pure CONTROL-based mapping would silently skip roughly half the device types. Key the mapping on the channel `TYPE` from the device metadata (always present) and use CONTROL only as a refinement where the cache has it (live fetches and the B-1 regen bring CONTROL in; the fetch tool stores the full response). B-3 is not a prerequisite (HA commands use the setValue path, which casts in the connection), but its trivial fixes ride along. Builds on Phase 3's extracted `lib/topic.js` so the HA node computes exactly ccu-mqtt's topics. **Runs on branch `b-16-homeassistant`, target 4.2.0** (decided 2026-09-04; 4.1.0 stays the small data release). **Status 2026-09-04: implemented on the branch** — `nodes/lib/haroles.js` + `nodes/lib/hadiscovery.js` (pure, 24 unit tests on paramsets.json fixtures), `nodes/ccu-homeassistant.{js,html}` (device table, ccu-mqtt reference, republish on input, removal configs), `type=devices` admin endpoint, ccu-mqtt command words (OPEN/CLOSE/STOP/ON/OFF, HM `*-MODE`) + empty-name topic fix + connection `deregister` fix, README section, `examples/home-assistant.json`, CHANGELOG "Unreleased (4.2.0)". **Verified end-to-end 2026-09-04** on the lab CCU3 (RedMatic 9.0.0-alpha, aedes broker inside Node-RED) against Home Assistant 2026.9.0 (docker): HmIPW-DRS8 → 8 switches (state from the transmitter channel, secondaries disabled), HmIPW-DRI16 → 16 opening sensors + 16 event entities, HmIPW-DRAP → bus voltage/current sensors; switch round trip HA → `hm/set` → CCU → `hm/status` → HA state on/off; untick + deploy removes the device from HA. Three payload defects found and fixed only because of the live test (HA rejected/ignored silently): an availability-list entry takes `val_tpl`, not `avty_tpl`; a switch needs explicit `stat_on`/`stat_off` because HA compares the templated state with the command payloads by default; a sensor/number must not carry a binary_sensor class (`running` on the ENUM datapoint PROCESS). The first two are inherited from hm2mqtt.js / mqtt-interfaces-core and should be fixed upstream too. Also fixed: the readiness wait treated an empty VALUES paramset as "not cached" (5-minute fallback delay). Second round on the OpenCCU lab box (same HA, second ccu-mqtt with prefix `hm2/` and **plain payloads**, so the non-JSON templates are covered too): HmIP-PDT → light with brightness (HA brightness 128 → `LEVEL` 0.5 → state on/128 from the DIMMER_TRANSMITTER channel, off → 0, plain on → last brightness), HmIP-WRC2 → 2 event entities + battery sensor, no HA warnings. **Second consumer:** [she](https://github.com/hobbyquaker/she) 1.51.1 (the author's dev instance on the test broker, which both lab flows now feed as well) parses the same retained payloads (`GET /she/mqtt/ha-discovery`) into the 5 lab devices with plausible entity groups and no orphaned/duplicate flags — she is the lighter, scriptable check for future B-16 changes; HA stays the reference for schema validation. Not covered by the lab: cover and climate payloads (no blind or thermostat paired anywhere), key presses on real hardware. **Open before merge:** editor smoke test in a browser (device table, ccu-mqtt select), CI run (the local mocha suite cannot bind port 8181 under WSL); cover/climate stay unit-test-only until a device is available. Merge after 4.1.0 ships. Known gaps upstream too: RGBW lights, sirens, garage doors, sysvars/programs as entities. | user request |