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

package/nodes/locales/de/matterbridge-config.html

@@ -0,0 +1,34 @@
+<script type="text/markdown" data-help-name="matterbridge-config">
+# Matter Bridge (BETA)
+
+> Dieser Node ist in **BETA**: Er funktioniert, aber Details können sich zwischen Releases noch ändern.
+
+## Übersicht
+
+Dieser Konfigurations-Node ist die **Matter-Bridge selbst**: Er betreibt den Matter-Server, den Alexa, Google Home, Apple Home (oder jeder Matter-Controller) **einmal** koppeln. Jeder **Matter Bridge device**-Node in deinen Flows verweist hierher und erscheint in den Apps als ein Gerät der Bridge.
+
+## Konfiguration
+
+|Feld|Beschreibung|
+|--|--|
+| Name | Der Name dieses Konfigurations-Nodes in Node-RED |
+| Name der Matter-Bridge | Wie die Bridge selbst in den Matter-Apps heißt |
+| Port | UDP-Port des Matter-Servers (Standard 5540). Jede Bridge braucht ihren eigenen Port, daher sind **mehrere unabhängige Bridges** möglich |
+
+## Kopplung
+
+1. **Deployen**, ein paar Sekunden warten, dann diesen Node erneut öffnen.
+2. Das Kopplungs-Panel zeigt den **QR-Code** und den **manuellen Code**: scannen oder in Alexa / Google Home / Apple Home eingeben ("Matter-Gerät hinzufügen").
+3. Mehrere Controller können mit derselben Bridge gekoppelt werden (Matter Multi-Fabric).
+
+Der Button **Kopplung zurücksetzen** entfernt alle gekoppelten Controller und startet die Kopplungs-Ankündigung neu.
+
+## Identität und Speicherung
+
+Die Bridge-Identität ist an diesen Konfigurations-Node gebunden und wird in `knxultimatestorage/matter` im Node-RED-Benutzerverzeichnis gespeichert: Re-Deploys (auch mit geändertem Port oder Namen) erfordern **KEINE** neue Kopplung. Nur das Löschen dieses Konfigurations-Nodes und das Anlegen eines neuen ändert die Identität — in dem Fall die alte Bridge aus der Matter-App entfernen und neu koppeln.
+
+## Hinweise
+
+- Der Node-RED-Host muss **IPv6 link-local** aktiviert haben (Standard-Matter-Anforderung) und von den Controllern im lokalen Netzwerk erreichbar sein.
+- Hinzugefügte/umbenannte/entfernte Device-Nodes werden von den gekoppelten Controllern innerhalb von Sekunden übernommen, ohne neue Kopplung.
+</script>

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

@@ -0,0 +1,20 @@
+{
+  "matterbridge-config": {
+    "properties": {
+      "title": "Matter Bridge",
+      "intro": "Dieser Konfigurations-Node ist die Matter-Bridge selbst: Alexa, Google Home, Apple Home (oder jeder Matter-Controller) koppeln sie einmal und sehen alle KNX-Geräte, die du ihr zuweist. Füge \"Matter Bridge device\"-Nodes in deinen Flows hinzu und verweise sie hierher. Zuerst deployen, dann erneut öffnen für den Kopplungscode.",
+      "node-config-input-name": "Name",
+      "bridge_name": "Name der Matter-Bridge",
+      "port": "Port",
+      "pairing_title": "Kopplung (Alexa, Google Home, Apple Home...)",
+      "not_running": "Die Matter-Bridge läuft noch nicht. Deployen, ein paar Sekunden warten und dann auf Aktualisieren klicken.",
+      "commissioned": "Bridge mit diesen Controllern gekoppelt:",
+      "awaiting": "Warte auf Kopplung. Scanne den QR-Code oder gib den manuellen Code in deiner Matter-App ein:",
+      "qr_link": "QR-Code im Browser öffnen",
+      "deploy_first": "Bitte zuerst diesen Konfigurations-Node deployen und dann auf Aktualisieren klicken.",
+      "reset_button": "Kopplung zurücksetzen",
+      "reset_confirm": "ALLE gekoppelten Controller entfernen und die Kopplung neu starten? Die Geräte verschwinden aus Alexa/Google/Apple.",
+      "reset_ok": "Kopplung zurückgesetzt. Die Bridge wartet wieder auf Kopplung."
+    }
+  }
+}

package/nodes/locales/en/knxUltimateMatterBridge.html

@@ -0,0 +1,53 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterBridge">
+# Matter Bridge device (BETA)
+
+> This node is in **BETA**: it works, but details may still change between releases.
+
+## Overview
+
+Each Matter Bridge device node exposes **one KNX device as a Matter device**: the paired controllers (Alexa, Google Home, Apple Home...) see it, with the name you typed, ready for app and voice control. Point it to a **Matter Bridge** configuration node (the actual bridge, paired once - the pairing QR code lives there) and add as many device nodes as you want, anywhere in your flows.
+
+This is the opposite direction of the *Matter Device* node: there KNX controls a Matter device, here the Matter controllers control KNX.
+
+## Configuration
+
+|Field|Description|
+|--|--|
+| Matter bridge | The Matter Bridge configuration node this device belongs to |
+| KNX GW | KNX gateway used for telegrams. **Optional**: without it the device runs in flow-only mode via the node PINs. Auto-selected when your project has only one gateway |
+| Name | What Alexa & Co. show and use for voice commands |
+| Device type | The Matter device type (see below); it drives which group address fields appear |
+| Read status at startup | Sends a `GroupValue_Read` to the status GAs at startup, so the Matter attributes are populated |
+
+## Device types and group addresses
+
+|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: assistant commands ("start cleaning", pause/resume/go home) arrive on the output as `rvcmode`/`rvccommand`; report the state back with `msg.payload = { function: "rvcstate", value: "running"|"docked"|"charging"|"paused"|"error" }` and the mode with `function: "rvcmode", value: "cleaning"|"idle"` |
+
+- **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.
+
+## Node PINs
+
+If you enable the node input/output PINs:
+
+- **Input**: update the Matter state from the flow, without the KNX bus: `msg.payload = { function: "onoff", value: true }` (`function` is one of `onoff`, `level`, `rgb`, `colortemp`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`, `fanspeed`, `smoke`, `co`, `leak`, `co2`, `rvcstate`, `rvcmode`). 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. A device without command GAs becomes a **flow-only device**.
+
+## Notes
+
+- The Matter identity of the device is tied to this node: deleting the node and creating a new one makes the apps see a brand-new device.
+- Added/renamed/removed device nodes are picked up by the paired controllers within seconds, without re-pairing the bridge.
+</script>

package/nodes/locales/en/knxUltimateMatterBridge.json

@@ -0,0 +1,83 @@
+{
+  "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."
+    },
+    "bridge": "Matter bridge",
+    "device_name": "Name (shown by Alexa & Co.)",
+    "device_help": "Pick the device type and give it the name the voice assistant will use, then fill the group addresses. The KNX gateway is optional: without it, enable the node PINs and drive the device from the flow."
+  },
+  "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/en/matterbridge-config.html

@@ -0,0 +1,34 @@
+<script type="text/markdown" data-help-name="matterbridge-config">
+# Matter Bridge (BETA)
+
+> This node is in **BETA**: it works, but details may still change between releases.
+
+## Overview
+
+This configuration node is the **Matter bridge itself**: it runs the Matter server that Alexa, Google Home, Apple Home (or any Matter controller) commission **once**. Every **Matter Bridge device** node in your flows points here and appears in the apps as one bridged device.
+
+## Configuration
+
+|Field|Description|
+|--|--|
+| Name | The name of this configuration node in Node-RED |
+| Matter bridge name | How the bridge itself is named in the Matter apps |
+| Port | UDP port of the Matter server (default 5540). Each bridge needs its own port, so you can run **multiple independent bridges** |
+
+## Pairing
+
+1. **Deploy**, wait a few seconds, then open this 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.
+
+## Identity and storage
+
+The bridge identity is tied to this configuration node and stored in `knxultimatestorage/matter` inside the Node-RED user directory: re-deploys (even changing port or name) do **NOT** require a new pairing. Only deleting this configuration node and creating a new one changes the identity — in that case remove the old bridge from the Matter app and pair again.
+
+## Notes
+
+- The Node-RED host must have **IPv6 link-local** enabled (standard Matter requirement) and be reachable from the controllers on the local network.
+- Device nodes added/renamed/removed are picked up by the paired controllers within seconds, without re-pairing.
+</script>

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

@@ -0,0 +1,20 @@
+{
+  "matterbridge-config": {
+    "properties": {
+      "title": "Matter Bridge",
+      "intro": "This configuration node is the Matter bridge itself: Alexa, Google Home, Apple Home (or any Matter controller) pair it once and see every KNX device you attach to it. Add \"Matter Bridge device\" nodes across your flows and point them here. Deploy first, then reopen to get the pairing code.",
+      "node-config-input-name": "Name",
+      "bridge_name": "Matter bridge name",
+      "port": "Port",
+      "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 configuration 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."
+    }
+  }
+}

package/nodes/locales/es/knxUltimateMatterBridge.html

@@ -0,0 +1,53 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterBridge">
+# Matter Bridge device (BETA)
+
+> Este nodo está en **BETA**: funciona, pero algunos detalles pueden cambiar entre versiones.
+
+## Descripción general
+
+Cada nodo Matter Bridge device expone **un dispositivo KNX como dispositivo Matter**: los controladores emparejados (Alexa, Google Home, Apple Home...) lo ven, con el nombre que hayas elegido, listo para el control por app y por voz. Apúntalo a un nodo de configuración **Bridge Matter** (el bridge en sí, emparejado una sola vez - el QR de emparejamiento vive allí) y añade tantos nodos de dispositivo como quieras, en cualquier flow.
+
+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|
+|--|--|
+| Bridge Matter | El nodo de configuración Bridge Matter al que pertenece este dispositivo |
+| GW KNX | Gateway KNX usado para los telegramas. **Opcional**: sin él, el dispositivo funciona en modo solo-flow mediante los PINes del nodo. Se selecciona automáticamente si el proyecto tiene un solo gateway |
+| Nombre | Lo que Alexa y cía. muestran y usan para los comandos de voz |
+| Tipo de dispositivo | El tipo de dispositivo Matter (ver abajo); determina qué campos de dirección de grupo aparecen |
+| Leer estado al inicio | Envía un `GroupValue_Read` a las GA de estado al inicio, para poblar los atributos Matter |
+
+## Tipos de dispositivo y direcciones de grupo
+
+|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 = { function: "rvcstate", value: "running"\|"docked"\|"charging"\|"paused"\|"error" }` y el modo con `function: "rvcmode", value: "cleaning"\|"idle"` |
+
+- **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).
+
+## PINes del nodo
+
+Si habilitas los PINes de entrada/salida del nodo:
+
+- **Entrada**: actualiza el estado Matter desde el flow, sin pasar por el bus KNX: `msg.payload = { function: "onoff", value: true }` (`function` es una de `onoff`, `level`, `rgb`, `colortemp`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`, `fanspeed`, `smoke`, `co`, `leak`, `co2`, `rvcstate`, `rvcmode`). Ú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. Un dispositivo sin GA de comando se convierte en un **dispositivo solo-flow**.
+
+## Notas
+
+- La identidad Matter del dispositivo está ligada a este nodo: si borras el nodo y creas uno nuevo, las apps ven un dispositivo completamente nuevo.
+- Los nodos de dispositivo añadidos/renombrados/eliminados se detectan en pocos segundos, sin volver a emparejar el bridge.
+</script>

package/nodes/locales/es/knxUltimateMatterBridge.json

@@ -0,0 +1,83 @@
+{
+  "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."
+    },
+    "bridge": "Bridge Matter",
+    "device_name": "Nombre (mostrado por Alexa y cía.)",
+    "device_help": "Elige el tipo de dispositivo y dale el nombre que usará el asistente de voz, luego rellena las direcciones de grupo. El gateway KNX es opcional: sin él, habilita los PINes del nodo y controla el dispositivo desde el flow."
+  },
+  "common": {
+    "ga": "GA",
+    "dpt": "DPT",
+    "name": "Nombre",
+    "knx_gw": "GW KNX"
+  }
+}