node-red-contrib-knx-ultimate 5.0.4 → 5.2.1

package/nodes/locales/de/matter-config.json

@@ -0,0 +1,26 @@
+{
+  "matter-config": {
+    "properties": {
+      "title": "Matter Controller",
+      "intro": "Dieser Node ist ein Matter-Controller (mit eigener Fabric). Kopple hier deine Matter-Geräte und verwende dann den \"Matter Device\"-Node, um sie auf KNX-Gruppenadressen abzubilden. Zuerst deployen, dann hierher zurückkehren, um Geräte zu koppeln.",
+      "node-config-input-name": "Name",
+      "fabric_label": "Fabric-Bezeichnung",
+      "pairing_title": "Neues Gerät koppeln",
+      "pairing_help": "Gib den 11-stelligen manuellen Kopplungscode (z.B. 3497-011-2332) oder den QR-Code-Inhalt (MT:....) ein. Das Gerät muss über das IP-Netzwerk erreichbar sein (WLAN/Ethernet oder Thread über Border Router). Ist das Gerät bereits mit einem anderen Controller (Alexa, Google, Apple) gekoppelt, nutze dessen Funktion \"mit weiterem Hub teilen\", um einen neuen Code zu erhalten.",
+      "pairing_code": "Kopplungscode",
+      "pair_button": "KOPPELN",
+      "devices_title": "Gekoppelte Geräte",
+      "col_name": "Name",
+      "col_product": "Produkt",
+      "col_state": "Status",
+      "no_devices": "Noch keine Geräte gekoppelt.",
+      "unpair_confirm": "Gerät entfernen (dekommissionieren)",
+      "unpair_ok": "Gerät entfernt.",
+      "deploy_first": "Bitte zuerst diesen Konfigurations-Node deployen und erneut versuchen.",
+      "pairing_code_missing": "Bitte einen Kopplungscode eingeben.",
+      "pairing_wait": "Kopplung läuft. Dies kann bis zu einer Minute dauern...",
+      "pairing_failed": "Kopplung fehlgeschlagen",
+      "pairing_ok": "Gerät erfolgreich gekoppelt!"
+    }
+  }
+}

package/nodes/locales/en/knxUltimateMatterBridge.html

@@ -0,0 +1,64 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterBridge">
+# Matter Bridge (BETA)
+
+> This node is in **BETA**: it works, but details may still change between releases.
+
+## Overview
+
+The Matter Bridge node exposes **KNX group addresses as Matter devices**: Alexa, Google Home, Apple Home (or any Matter controller) commission this bridge **once** and see all your configured KNX devices, with the names you typed, ready for app and voice control.
+
+This is the opposite direction of the *Matter Device* node: there KNX controls a Matter device, here Matter controllers control KNX.
+
+## Configuration
+
+|Field|Description|
+|--|--|
+| KNX GW | KNX gateway used for telegrams. **Optional**: without a gateway the bridge works in flow-only mode — enable the node PINs and drive every device with flow messages |
+| Matter bridge name | How the bridge itself is named in the Matter apps |
+| Port | UDP port of the Matter server (default 5540). Only one bridge node per Node-RED instance. |
+| Devices | The KNX virtual devices exposed on Matter (see below) |
+| Read status at startup | Sends a `GroupValue_Read` to every status GA at startup, so the Matter attributes are populated |
+
+## Devices
+
+Each row is one device shown by Alexa & Co. Pick the **type**, give it the **name** the assistant will use, then fill the group addresses (with ETS autocomplete):
+
+|Type|Group addresses|
+|--|--|
+| On/Off light, Plug | On/Off command GA, On/Off status GA (DPT 1.001) |
+| Dimmable light | + Dimming % command/status GA (DPT 5.001) |
+| RGB color light | + RGB color command/status GA (DPT 232.600). The Matter color (hue/saturation or XY, from the app color wheel) is converted to/from the KNX RGB triplet |
+| Tunable white light | + Color temperature command/status GA in Kelvin (DPT 7.600) |
+| Cover / Shutter | Up/Down (DPT 1.008), Stop (DPT 1.017), Position % command/status (DPT 5.001), optional position inversion |
+| Thermostat (heating) | Current temperature GA, Setpoint command/status GA (DPT 9.001) |
+| Fan / Ventilation | Fan speed % command/status GA (DPT 5.001) |
+| Sensors (temperature, humidity, light, occupancy, contact) | One status GA each |
+| Smoke/CO alarm | Smoke alarm status GA + optional CO alarm status GA (DPT 1.005): critical notifications on the phone |
+| Water leak detector | Leak status GA (DPT 1.005) |
+| Air quality sensor (CO2) | CO2 status GA in ppm (DPT 9.008); the air quality class (good/fair/moderate/poor...) is derived automatically |
+| Robot vacuum | **Flow-only**: no group addresses. Enable the node PINs: commands from the assistant ("start cleaning", pause/resume/go home) arrive on the output as `rvcmode`/`rvccommand`; report the state back with `msg.payload = { device, function: "rvcstate", value: "running"|"docked"|"charging"|"paused"|"error" }` and the mode with `function: "rvcmode", value: "cleaning"|"idle"`. Integrate your Roomba/Roborock with any Node-RED node and expose it to Alexa/Apple |
+
+- **Command GA**: written to the KNX bus when the assistant sends a command.
+- **Status GA**: read from the bus to keep the Matter attributes (and the apps) updated.
+
+## Pairing
+
+1. **Deploy**, wait a few seconds, then open the node again.
+2. The pairing panel shows the **QR code** and the **manual pairing code**: scan or type it in Alexa / Google Home / Apple Home ("add Matter device").
+3. Multiple controllers can be paired with the same bridge (Matter multi-fabric).
+
+The **Reset pairing** button removes all paired controllers and restarts the pairing advertising.
+
+## Node PINs
+
+If you enable the node input/output PINs:
+
+- **Input**: update the Matter state of a virtual device from the flow, without going through the KNX bus: `msg.payload = { device: "Kitchen light", function: "onoff", value: true }` (`device` accepts the name or the internal id; `function` is one of `onoff`, `level`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`). Useful to expose flow-computed values (e.g. a virtual sensor) to Alexa & Co.
+- **Output**: every command received from a Matter controller is forwarded to the flow: `msg.topic` = device name, `msg.payload` = value, `msg.matter` = the raw command. Devices without a command GA become **flow-only devices**: the command reaches your flow and you decide what to do with it.
+
+## Notes
+
+- The Node-RED host must have **IPv6 link-local** enabled (standard Matter requirement) and be reachable from the controller on the local network.
+- The bridge identity is stored in `knxultimatestorage/matter` inside the Node-RED user directory: re-deploys do NOT require a new pairing.
+- Device renames/additions are picked up by the controllers automatically; if you remove a device, it disappears from the apps.
+</script>

package/nodes/locales/en/knxUltimateMatterBridge.json

@@ -0,0 +1,80 @@
+{
+  "knxUltimateMatterBridge": {
+    "title": "Matter Bridge (BETA)",
+    "bridge_name": "Matter bridge name",
+    "port": "Port",
+    "devices_help": "Add the KNX devices to expose on Matter. The \"Name\" is what Alexa/Google/Apple will show and use for voice commands. Command GA = written when the assistant sends a command; Status GA = read from the bus to keep the app updated.",
+    "read_status_startup": "Read the status group addresses at startup",
+    "opt_yes": "Yes",
+    "opt_no": "No",
+    "node_pins": "Node Input/Output PINs",
+    "node_pins_hide": "Hide",
+    "node_pins_show": "Show node input/output PINs",
+    "fields": {
+      "type": "Device type",
+      "name": "Name (shown by Alexa & Co.)",
+      "name_placeholder": "e.g. Kitchen light",
+      "invert": "Invert position %"
+    },
+    "functions": {
+      "fn_onoff_cmd": "On/Off command GA",
+      "fn_onoff_status": "On/Off status GA",
+      "fn_level_cmd": "Dimming % command GA",
+      "fn_level_status": "Dimming % status GA",
+      "fn_sensor_ga": "Sensor status GA",
+      "fn_updown": "Up/Down command GA",
+      "fn_stop": "Stop command GA",
+      "fn_position_cmd": "Position % command GA",
+      "fn_position_status": "Position % status GA",
+      "fn_currenttemp": "Current temperature GA",
+      "fn_setpoint_cmd": "Setpoint command GA",
+      "fn_setpoint_status": "Setpoint status GA",
+      "fn_rgb_cmd": "RGB color command GA (DPT 232.600)",
+      "fn_rgb_status": "RGB color status GA (DPT 232.600)",
+      "fn_ct_cmd": "Color temperature command GA (Kelvin)",
+      "fn_ct_status": "Color temperature status GA (Kelvin)",
+      "fn_smoke_ga": "Smoke alarm status GA",
+      "fn_co_ga": "CO alarm status GA (optional)",
+      "fn_leak_ga": "Leak status GA",
+      "fn_co2_ga": "CO2 status GA (ppm, DPT 9.008)",
+      "fn_fanspeed_cmd": "Fan speed % command GA",
+      "fn_fanspeed_status": "Fan speed % status GA"
+    },
+    "types": {
+      "onofflight": "On/Off light",
+      "dimmablelight": "Dimmable light",
+      "rgblight": "RGB color light",
+      "colortemperaturelight": "Tunable white light (color temperature)",
+      "onoffplug": "Plug / Socket (on/off)",
+      "temperaturesensor": "Temperature sensor",
+      "humiditysensor": "Humidity sensor",
+      "lightsensor": "Light sensor (Lux)",
+      "occupancysensor": "Occupancy sensor",
+      "contactsensor": "Contact sensor",
+      "windowcovering": "Cover / Shutter",
+      "thermostat": "Thermostat (heating)",
+      "fan": "Fan / Ventilation",
+      "smokecoalarm": "Smoke/CO alarm",
+      "waterleakdetector": "Water leak detector",
+      "airqualitysensor": "Air quality sensor (CO2)",
+      "robotvacuum": "Robot vacuum (flow-only, via node PINs)"
+    },
+    "pairing": {
+      "title": "Pairing (Alexa, Google Home, Apple Home...)",
+      "not_running": "The Matter bridge is not running yet. Deploy, wait a few seconds, then click refresh.",
+      "commissioned": "Bridge paired with these controllers:",
+      "awaiting": "Awaiting pairing. Scan the QR code or enter the manual code in your Matter app:",
+      "qr_link": "Open the QR code in the browser",
+      "deploy_first": "Deploy this node first, then click refresh.",
+      "reset_button": "Reset pairing",
+      "reset_confirm": "Remove ALL paired controllers and restart pairing? The devices will disappear from Alexa/Google/Apple.",
+      "reset_ok": "Pairing reset. The bridge is now advertising for pairing again."
+    }
+  },
+  "common": {
+    "ga": "GA",
+    "dpt": "DPT",
+    "name": "Name",
+    "knx_gw": "KNX GW"
+  }
+}

package/nodes/locales/en/knxUltimateMatterDevice.html

@@ -0,0 +1,56 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterDevice">
+# Matter Device (BETA)
+
+> This node is in **BETA**: it works, but details may still change between releases.
+
+## Overview
+
+The Matter Device node bridges a **Matter device** to **KNX group addresses**. The node acts through the *Matter Controller* configuration node, which commissions (pairs) the devices into its own Matter fabric.
+
+- **Control** any commissioned Matter device from the KNX bus (on/off, dimming, covers, thermostats, locks, ...).
+- **Track** every attribute of the device on KNX group addresses (status feedback, sensors, power metering, battery...).
+- Fully generic: the mapping list is built from the **real endpoints/clusters** exposed by the device.
+
+## Configuration
+
+|Field|Description|
+|--|--|
+| KNX GW | KNX gateway used for telegrams |
+| Matter Ctrl | The Matter Controller configuration node (where you pair the devices) |
+| Device | Pick the commissioned Matter device from the autocomplete list |
+| Mappings | One row per group address ↔ Matter cluster mapping |
+| Read status at startup | When enabled, the node emits the current cached values on deploy/connection |
+| Node Input/Output PINs | Enable Node-RED input/output pins for raw Matter access |
+
+## Mappings
+
+The target list shows the supported functions with friendly names such as *"On/Off switch"* or *"Instantaneous power (W)"*, filtered on what the device really exposes and with the current value shown in brackets.
+
+Each mapping row has a **direction**:
+
+- **KNX → Matter (command)**: a telegram received on the group address invokes a Matter cluster command or writes an attribute. Example: GA `1/1/1` DPT 1.001 → `OnOff.on/off` (the boolean payload selects on or off automatically).
+- **Matter → KNX (status)**: whenever the subscribed Matter attribute changes, its value is converted and written to the group address. `GroupValue_Read` requests are answered with the cached value.
+
+Well-known clusters are converted automatically to KNX-friendly values:
+
+|Cluster|Conversion|
+|--|--|
+| OnOff | boolean (DPT 1.001) |
+| LevelControl | 0-254 ↔ percent (DPT 5.001) |
+| WindowCovering | percent100ths ↔ percent (DPT 5.001), up/down (DPT 1.008) |
+| ColorControl | mireds ↔ Kelvin (DPT 7.600) |
+| Thermostat | centi-°C ↔ °C (DPT 9.001) |
+| Temperature/Humidity | centi-units ↔ units (DPT 9.001/9.007) |
+| Illuminance | log scale ↔ Lux (DPT 9.004) |
+| PowerSource | half-percent ↔ percent battery (DPT 5.001) |
+| Electrical Power/Energy | mW ↔ W (DPT 14.056), mWh ↔ kWh (DPT 13.013) |
+
+Other clusters/attributes are passed through raw; the DPT you pick performs the final KNX encoding.
+
+## Node PINs
+
+If you enable the node PINs:
+
+- **Input**: send raw commands: `msg.payload = { endpointId: 1, clusterId: 6, command: "toggle" }` or attribute writes: `msg.payload = { endpointId: 1, clusterId: 8, attribute: "onLevel", value: 128 }`
+- **Output**: receives every attribute change (`msg.matter` contains the full event) and every cluster event (button presses etc.).
+</script>

package/nodes/locales/en/knxUltimateMatterDevice.json

@@ -0,0 +1,109 @@
+{
+  "knxUltimateMatterDevice": {
+    "title": "Matter Device (BETA)",
+    "paletteLabel": "Matter Device (BETA)",
+    "matter_controller": "Matter Ctrl",
+    "matter_device": "Device",
+    "device_placeholder": "Click to pick a paired Matter device",
+    "mapping_help": "Add one row per mapping. \"KNX → Matter\" invokes a cluster command (or writes an attribute) when a telegram arrives on the group address. \"Matter → KNX\" writes the attribute value to the group address whenever it changes (read requests are answered with the cached value).",
+    "select_target": "-- select the Matter target --",
+    "stored_target": "Stored",
+    "read_status_startup": "Read status at startup",
+    "opt_yes_emit": "Yes, and emit KNX telegrams.",
+    "opt_no": "No",
+    "node_pins": "Node Input/Output PINs",
+    "node_pins_hide": "Hide",
+    "node_pins_show": "Show node input/output PINs",
+    "direction": {
+      "command": "KNX → Matter (command)",
+      "status": "Matter → KNX (status)"
+    },
+    "fields": {
+      "direction": "Direction",
+      "target": "Matter endpoint / cluster / target",
+      "ga": "Group address",
+      "dpt": "DPT",
+      "ganame": "Name"
+    },
+    "no_simple_targets": "No supported functions found on this device (or the device is not connected yet).",
+    "endpoint": "Endpoint",
+    "friendly": {
+      "onoff_switch": "On/Off switch (turn on/off)",
+      "onoff_toggle": "Toggle (invert state)",
+      "onoff_state": "On/Off state",
+      "level_set": "Set brightness / level (%)",
+      "level_state": "Current brightness / level (%)",
+      "colortemp_set": "Set color temperature (Kelvin)",
+      "colortemp_state": "Current color temperature (Kelvin)",
+      "cover_updown": "Cover Up/Down",
+      "cover_stop": "Cover Stop",
+      "cover_position_set": "Move cover to position (%)",
+      "cover_position_state": "Current cover position (%)",
+      "cover_tilt_set": "Move slats to tilt (%)",
+      "cover_tilt_state": "Current slat tilt (%)",
+      "thermo_localtemp": "Room temperature (°C)",
+      "thermo_heatsp_set": "Set heating setpoint (°C)",
+      "thermo_coolsp_set": "Set cooling setpoint (°C)",
+      "thermo_heatsp_state": "Heating setpoint (°C)",
+      "thermo_coolsp_state": "Cooling setpoint (°C)",
+      "fan_speed_set": "Set fan speed (%)",
+      "fan_speed_state": "Current fan speed (%)",
+      "lock_cmd": "Lock/Unlock door",
+      "lock_state": "Lock state (locked)",
+      "temp_measured": "Measured temperature (°C)",
+      "humidity_measured": "Relative humidity (%)",
+      "illuminance_measured": "Illuminance (Lux)",
+      "occupancy_state": "Presence detected",
+      "contact_state": "Contact state (closed/open)",
+      "battery_percent": "Battery level (%)",
+      "power_active": "Instantaneous power (W)",
+      "power_voltage": "Voltage (V)",
+      "power_current": "Current (A)",
+      "energy_imported": "Energy consumed (kWh)",
+      "identify_cmd": "Identify device (blink)",
+      "switch_position": "Button position"
+    },
+    "devtype": {
+      "onofflight": "On/Off light",
+      "dimmablelight": "Dimmable light",
+      "colortemperaturelight": "Color temperature light",
+      "extendedcolorlight": "Color light",
+      "onoffpluginunit": "Plug (on/off)",
+      "dimmablepluginunit": "Plug (dimmable)",
+      "smartplug": "Smart plug",
+      "contactsensor": "Contact sensor",
+      "lightsensor": "Light sensor",
+      "occupancysensor": "Occupancy sensor",
+      "temperaturesensor": "Temperature sensor",
+      "humiditysensor": "Humidity sensor",
+      "pressuresensor": "Pressure sensor",
+      "flowsensor": "Flow sensor",
+      "doorlock": "Door lock",
+      "windowcovering": "Window covering",
+      "thermostat": "Thermostat",
+      "fan": "Fan",
+      "genericswitch": "Button/Switch",
+      "airqualitysensor": "Air quality sensor",
+      "smokecoalarm": "Smoke/CO alarm",
+      "waterleakdetector": "Water leak detector",
+      "roomairconditioner": "Air conditioner",
+      "airpurifier": "Air purifier",
+      "speaker": "Speaker",
+      "pumpcontroller": "Pump",
+      "onofflightswitch": "Light switch",
+      "dimmerswitch": "Dimmer switch",
+      "colordimmerswitch": "Color dimmer switch",
+      "powersource": "Power source",
+      "electricalsensor": "Electrical sensor",
+      "bridgednode": "Bridged device",
+      "aggregator": "Bridge/Aggregator",
+      "rootnode": "Root node"
+    }
+  },
+  "common": {
+    "ga": "GA",
+    "dpt": "DPT",
+    "name": "Name",
+    "knx_gw": "KNX GW"
+  }
+}

package/nodes/locales/en/matter-config.html

@@ -0,0 +1,25 @@
+<script type="text/markdown" data-help-name="matter-config">
+# Matter Controller
+
+## Overview
+
+This configuration node is a full **Matter controller**: it creates its own Matter *fabric* and commissions (pairs) your Matter devices into it. The paired devices are then available to the **Matter Device** nodes, which map them to KNX group addresses.
+
+The controller talks to the devices over the **IP network** (WiFi, Ethernet, or Thread through a border router). Bluetooth commissioning is not supported: the device must already be reachable on the network.
+
+## Pairing a device
+
+1. **Deploy** this configuration node first (the controller must be running).
+2. Open the node again and enter the **pairing code**: either the 11-digit manual code (e.g. `3497-011-2332`) or the QR code content (`MT:....`).
+3. Click **PAIR**. Commissioning can take up to a minute.
+
+If the device is brand new and only supports Bluetooth commissioning, first pair it with its vendor app or another Matter controller (Alexa, Google Home, Apple Home), then use that controller's **"share / pair with another hub"** function to generate a new pairing code for KNX-Ultimate. This way the device joins multiple fabrics at once.
+
+## Storage
+
+The fabric credentials and the paired devices are stored in the `knxultimatestorage/matter` folder inside your Node-RED user directory. Deleting that folder unpairs everything.
+
+## Removing a device
+
+Use the trash button in the commissioned devices list. The controller tries to decommission the device properly; if it is unreachable, it is removed from the fabric anyway (a factory reset of the device may then be needed).
+</script>

package/nodes/locales/en/matter-config.json

@@ -0,0 +1,26 @@
+{
+  "matter-config": {
+    "properties": {
+      "title": "Matter Controller",
+      "intro": "This node is a Matter controller (its own fabric). Pair your Matter devices here, then use the \"Matter Device\" node to map them to KNX group addresses. Deploy the node first, then come back here to pair devices.",
+      "node-config-input-name": "Name",
+      "fabric_label": "Fabric label",
+      "pairing_title": "Pair a new device",
+      "pairing_help": "Enter the 11-digit manual pairing code (e.g. 3497-011-2332) or the QR code content (MT:....). The device must be reachable on the IP network (WiFi/Ethernet or Thread via border router). If the device is already paired with another controller (Alexa, Google, Apple), use its \"share/pair with another hub\" function to obtain a new pairing code.",
+      "pairing_code": "Pairing code",
+      "pair_button": "PAIR",
+      "devices_title": "Commissioned devices",
+      "col_name": "Name",
+      "col_product": "Product",
+      "col_state": "State",
+      "no_devices": "No devices paired yet.",
+      "unpair_confirm": "Remove (decommission) the device",
+      "unpair_ok": "Device removed.",
+      "deploy_first": "Deploy this configuration node first, then try again.",
+      "pairing_code_missing": "Please enter a pairing code.",
+      "pairing_wait": "Pairing in progress. It can take up to a minute...",
+      "pairing_failed": "Pairing failed",
+      "pairing_ok": "Device paired successfully!"
+    }
+  }
+}

package/nodes/locales/es/knxUltimateMatterBridge.html

@@ -0,0 +1,64 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterBridge">
+# Matter Bridge (BETA)
+
+> Este nodo está en **BETA**: funciona, pero algunos detalles pueden cambiar entre versiones.
+
+## Descripción general
+
+El nodo Matter Bridge expone las **direcciones de grupo KNX como dispositivos Matter**: Alexa, Google Home, Apple Home (o cualquier controlador Matter) emparejan este bridge **una sola vez** y ven todos tus dispositivos KNX configurados, con los nombres que hayas elegido, listos para el control por app y por voz.
+
+Es la dirección opuesta al nodo *Matter Device*: allí KNX controla un dispositivo Matter, aquí los controladores Matter controlan KNX.
+
+## Configuración
+
+|Campo|Descripción|
+|--|--|
+| GW KNX | Gateway KNX usado para los telegramas. **Opcional**: sin gateway el bridge funciona en modo solo-flow — habilita los PINes del nodo y controla cada dispositivo con mensajes del flow |
+| Nombre del bridge Matter | Cómo se llama el bridge en las apps Matter |
+| Puerto | Puerto UDP del servidor Matter (por defecto 5540). Solo un nodo bridge por instancia de Node-RED. |
+| Dispositivos | Los dispositivos KNX virtuales expuestos en Matter (ver abajo) |
+| Leer las GA de estado al inicio | Envía un `GroupValue_Read` a cada GA de estado al inicio, para poblar los atributos Matter |
+
+## Dispositivos
+
+Cada fila es un dispositivo mostrado por Alexa y cía. Elige el **tipo**, dale el **nombre** que usará el asistente y rellena las direcciones de grupo (con autocompletado ETS):
+
+|Tipo|Direcciones de grupo|
+|--|--|
+| Luz On/Off, Enchufe | GA comando On/Off, GA estado On/Off (DPT 1.001) |
+| Luz regulable | + GA comando/estado regulación % (DPT 5.001) |
+| Luz RGB (color) | + GA comando/estado color RGB (DPT 232.600). El color Matter (hue/saturation o XY, de la rueda de color de la app) se convierte desde/hacia la terna RGB KNX |
+| Luz blanco dinámico | + GA comando/estado temperatura de color en Kelvin (DPT 7.600) |
+| Persiana / Cortina | Subir/Bajar (DPT 1.008), Stop (DPT 1.017), posición % comando/estado (DPT 5.001), inversión de posición opcional |
+| Termostato (calefacción) | GA temperatura actual, GA comando/estado consigna (DPT 9.001) |
+| Ventilador / VMC | GA comando/estado velocidad % (DPT 5.001) |
+| Sensores (temperatura, humedad, luz, presencia, contacto) | Una GA de estado cada uno |
+| Alarma humo/CO | GA estado alarma de humo + GA estado alarma CO opcional (DPT 1.005): notificaciones críticas en el teléfono |
+| Detector de fugas de agua | GA estado fuga (DPT 1.005) |
+| Sensor de calidad del aire (CO2) | GA estado CO2 en ppm (DPT 9.008); la clase de calidad del aire (buena/regular/moderada/mala...) se deriva automáticamente |
+| Robot aspirador | **Solo-flow**: sin direcciones de grupo. Habilita los PINes del nodo: los comandos del asistente ("inicia la limpieza", pausa/reanudar/volver a la base) llegan a la salida como `rvcmode`/`rvccommand`; informa el estado con `msg.payload = { device, function: "rvcstate", value: "running"\|"docked"\|"charging"\|"paused"\|"error" }` y el modo con `function: "rvcmode", value: "cleaning"\|"idle"`. Integra tu Roomba/Roborock con cualquier nodo de Node-RED y exponlo a Alexa/Apple |
+
+- **GA de comando**: se escribe en el bus KNX cuando el asistente envía un comando.
+- **GA de estado**: se lee del bus para mantener actualizados los atributos Matter (y las apps).
+
+## Emparejamiento
+
+1. Haz **deploy**, espera unos segundos y vuelve a abrir el nodo.
+2. El panel de emparejamiento muestra el **código QR** y el **código manual**: escanéalo o escríbelo en Alexa / Google Home / Apple Home ("añadir dispositivo Matter").
+3. Se pueden emparejar varios controladores con el mismo bridge (multi-fabric Matter).
+
+El botón **Restablecer emparejamiento** elimina todos los controladores emparejados y reinicia el anuncio de emparejamiento.
+
+## PINes del nodo
+
+Si habilitas los PINes de entrada/salida del nodo:
+
+- **Entrada**: actualiza el estado Matter de un dispositivo virtual desde el flow, sin pasar por el bus KNX: `msg.payload = { device: "Luz cocina", function: "onoff", value: true }` (`device` acepta el nombre o el id interno; `function` es una de `onoff`, `level`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`). Útil para exponer a Alexa y cía. valores calculados en el flow (p.ej. un sensor virtual).
+- **Salida**: cada comando recibido de un controlador Matter se reenvía al flow: `msg.topic` = nombre del dispositivo, `msg.payload` = valor, `msg.matter` = el comando en bruto. Los dispositivos sin GA de comando se convierten en **dispositivos solo-flow**: el comando llega a tu flow y tú decides qué hacer con él.
+
+## Notas
+
+- El host de Node-RED debe tener **IPv6 link-local** habilitado (requisito estándar de Matter) y ser accesible desde el controlador en la red local.
+- La identidad del bridge se guarda en `knxultimatestorage/matter` dentro del directorio de usuario de Node-RED: los re-deploys NO requieren un nuevo emparejamiento.
+- Los cambios de nombre y los dispositivos añadidos se detectan automáticamente; si eliminas un dispositivo, desaparece de las apps.
+</script>

package/nodes/locales/es/knxUltimateMatterBridge.json

@@ -0,0 +1,80 @@
+{
+  "knxUltimateMatterBridge": {
+    "title": "Matter Bridge (BETA)",
+    "bridge_name": "Nombre del bridge Matter",
+    "port": "Puerto",
+    "devices_help": "Añade los dispositivos KNX a exponer en Matter. El \"Nombre\" es el que Alexa/Google/Apple muestran y usan para los comandos de voz. GA de comando = se escribe cuando el asistente envía un comando; GA de estado = se lee del bus para mantener la app actualizada.",
+    "read_status_startup": "Leer las direcciones de grupo de estado al inicio",
+    "opt_yes": "Sí",
+    "opt_no": "No",
+    "node_pins": "PINes de entrada/salida del nodo",
+    "node_pins_hide": "Ocultar",
+    "node_pins_show": "Mostrar PINes de entrada/salida",
+    "fields": {
+      "type": "Tipo de dispositivo",
+      "name": "Nombre (mostrado por Alexa y cía.)",
+      "name_placeholder": "p.ej. Luz cocina",
+      "invert": "Invertir posición %"
+    },
+    "functions": {
+      "fn_onoff_cmd": "GA comando On/Off",
+      "fn_onoff_status": "GA estado On/Off",
+      "fn_level_cmd": "GA comando regulación %",
+      "fn_level_status": "GA estado regulación %",
+      "fn_sensor_ga": "GA estado del sensor",
+      "fn_updown": "GA comando Subir/Bajar",
+      "fn_stop": "GA comando Stop",
+      "fn_position_cmd": "GA comando posición %",
+      "fn_position_status": "GA estado posición %",
+      "fn_currenttemp": "GA temperatura actual",
+      "fn_setpoint_cmd": "GA comando consigna",
+      "fn_setpoint_status": "GA estado consigna",
+      "fn_rgb_cmd": "GA comando color RGB (DPT 232.600)",
+      "fn_rgb_status": "GA estado color RGB (DPT 232.600)",
+      "fn_ct_cmd": "GA comando temperatura de color (Kelvin)",
+      "fn_ct_status": "GA estado temperatura de color (Kelvin)",
+      "fn_smoke_ga": "GA estado alarma de humo",
+      "fn_co_ga": "GA estado alarma CO (opcional)",
+      "fn_leak_ga": "GA estado fuga de agua",
+      "fn_co2_ga": "GA estado CO2 (ppm, DPT 9.008)",
+      "fn_fanspeed_cmd": "GA comando velocidad ventilador %",
+      "fn_fanspeed_status": "GA estado velocidad ventilador %"
+    },
+    "types": {
+      "onofflight": "Luz On/Off",
+      "dimmablelight": "Luz regulable",
+      "rgblight": "Luz RGB (color)",
+      "colortemperaturelight": "Luz blanco dinámico (temperatura de color)",
+      "onoffplug": "Enchufe (on/off)",
+      "temperaturesensor": "Sensor de temperatura",
+      "humiditysensor": "Sensor de humedad",
+      "lightsensor": "Sensor de luz (Lux)",
+      "occupancysensor": "Sensor de presencia",
+      "contactsensor": "Sensor de contacto",
+      "windowcovering": "Persiana / Cortina",
+      "thermostat": "Termostato (calefacción)",
+      "fan": "Ventilador / VMC",
+      "smokecoalarm": "Alarma humo/CO",
+      "waterleakdetector": "Detector de fugas de agua",
+      "airqualitysensor": "Sensor de calidad del aire (CO2)",
+      "robotvacuum": "Robot aspirador (solo flow, vía PINes del nodo)"
+    },
+    "pairing": {
+      "title": "Emparejamiento (Alexa, Google Home, Apple Home...)",
+      "not_running": "El bridge Matter aún no está en ejecución. Haz deploy, espera unos segundos y pulsa actualizar.",
+      "commissioned": "Bridge emparejado con estos controladores:",
+      "awaiting": "Esperando emparejamiento. Escanea el código QR o introduce el código manual en tu app Matter:",
+      "qr_link": "Abrir el código QR en el navegador",
+      "deploy_first": "Haz deploy de este nodo primero y pulsa actualizar.",
+      "reset_button": "Restablecer emparejamiento",
+      "reset_confirm": "¿Eliminar TODOS los controladores emparejados y reiniciar el emparejamiento? Los dispositivos desaparecerán de Alexa/Google/Apple.",
+      "reset_ok": "Emparejamiento restablecido. El bridge vuelve a estar en espera de emparejamiento."
+    }
+  },
+  "common": {
+    "ga": "GA",
+    "dpt": "DPT",
+    "name": "Nombre",
+    "knx_gw": "GW KNX"
+  }
+}

package/nodes/locales/es/knxUltimateMatterDevice.html

@@ -0,0 +1,56 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterDevice">
+# Dispositivo Matter (BETA)
+
+> Este nodo está en **BETA**: funciona, pero algunos detalles pueden cambiar entre versiones.
+
+## Descripción general
+
+El nodo Matter Device hace de puente entre un **dispositivo Matter** y las **direcciones de grupo KNX**. El nodo opera a través del nodo de configuración *Controlador Matter*, que comisiona los dispositivos en su propia fabric Matter.
+
+- **Controla** cualquier dispositivo Matter emparejado desde el bus KNX (on/off, regulación, persianas, termostatos, cerraduras, ...).
+- **Sigue** cada atributo del dispositivo en direcciones de grupo KNX (estados, sensores, medición de potencia, batería...).
+- Totalmente genérico: la lista de mapeos se construye a partir de los **endpoints/clústeres reales** que expone el dispositivo.
+
+## Configuración
+
+|Campo|Descripción|
+|--|--|
+| GW KNX | Gateway KNX usado para los telegramas |
+| Ctrl Matter | El nodo de configuración Controlador Matter (donde se emparejan los dispositivos) |
+| Dispositivo | Elige el dispositivo Matter emparejado desde el autocompletado |
+| Mapeos | Una fila por cada mapeo dirección de grupo ↔ clúster Matter |
+| Leer estado al inicio | Si está activo, el nodo emite los valores actuales en caché al hacer deploy/conectar |
+| PINes de entrada/salida | Habilita los pines de Node-RED para el acceso Matter en bruto |
+
+## Mapeos
+
+La lista de destinos muestra las funciones soportadas con nombres comprensibles como *"Interruptor On/Off"* o *"Potencia instantánea (W)"*, filtradas según lo que el dispositivo realmente expone y con el valor actual entre corchetes.
+
+Cada fila de mapeo tiene una **dirección**:
+
+- **KNX → Matter (comando)**: un telegrama recibido en la dirección de grupo invoca un comando del clúster Matter o escribe un atributo. Ejemplo: GA `1/1/1` DPT 1.001 → `OnOff.on/off` (el valor booleano elige automáticamente on u off).
+- **Matter → KNX (estado)**: cuando cambia el atributo Matter suscrito, su valor se convierte y se escribe en la dirección de grupo. Las peticiones `GroupValue_Read` se responden con el valor en caché.
+
+Los clústeres más comunes se convierten automáticamente en valores aptos para KNX:
+
+|Clúster|Conversión|
+|--|--|
+| OnOff | booleano (DPT 1.001) |
+| LevelControl | 0-254 ↔ porcentaje (DPT 5.001) |
+| WindowCovering | percent100ths ↔ porcentaje (DPT 5.001), subir/bajar (DPT 1.008) |
+| ColorControl | mireds ↔ Kelvin (DPT 7.600) |
+| Thermostat | centi-°C ↔ °C (DPT 9.001) |
+| Temperatura/Humedad | centi-unidades ↔ unidades (DPT 9.001/9.007) |
+| Iluminancia | escala logarítmica ↔ Lux (DPT 9.004) |
+| PowerSource | medio-porcentaje ↔ porcentaje de batería (DPT 5.001) |
+| Potencia/Energía eléctrica | mW ↔ W (DPT 14.056), mWh ↔ kWh (DPT 13.013) |
+
+Los demás clústeres/atributos pasan sin conversión; el DPT elegido realiza la codificación KNX final.
+
+## PINes del nodo
+
+Si habilitas los PINes del nodo:
+
+- **Entrada**: envía comandos en bruto: `msg.payload = { endpointId: 1, clusterId: 6, command: "toggle" }` o escrituras de atributos: `msg.payload = { endpointId: 1, clusterId: 8, attribute: "onLevel", value: 128 }`
+- **Salida**: recibe cada cambio de atributo (`msg.matter` contiene el evento completo) y cada evento de clúster (pulsaciones de botones, etc.).
+</script>