@airnexus/node-red-contrib-matter-airnexus 0.2.4-airnexus.1

package/ARCHITECTURE.md

@@ -0,0 +1,327 @@
+# Node-RED Matter Dynamic - Architecture Documentation
+
+## Project Overview
+
+This project implements dynamic Matter device nodes for Node-RED, allowing users to create Matter devices by specifying only the device type in JSON configuration, without hardcoding device-specific characteristics.
+
+## Key Components
+
+### 1. Matter Bridge (`matter-bridge.js` / `matter-bridge.html`)
+- **Purpose**: Creates a Matter Bridge that hosts multiple dynamic devices
+- **Key Features**:
+  - Manages Matter server lifecycle
+  - Handles device registration via `registerChild()` function
+  - Provides HTTP endpoints for commissioning QR codes
+  - Auto-starts when all registered devices are ready
+
+### 2. Matter Device (`matter-device.js` / `matter-device.html`)
+- **Purpose**: Generic node that can represent any Matter device type
+- **Configuration**: Simple JSON specifying only `deviceType` (e.g., "OnOffLightDevice")
+- **Key Features**:
+  - Dynamically subscribes to all device events
+  - Maps Matter.js cluster structure for input/output
+  - No hardcoded device-specific logic
+
+## Architecture Design
+
+### CRITICAL DESIGN PRINCIPLE: NO HARDCODED DEVICE-SPECIFIC LOGIC
+**This system MUST remain completely generic. NEVER hardcode behaviors, attributes, or logic for specific device types. All device capabilities must be discovered and handled dynamically at runtime.**
+
+### Device Creation Flow
+```
+1. User configures device with JSON: {"deviceType": "OnOffLightDevice"}
+2. Device node waits for bridge to be ready
+3. Creates Matter.js Endpoint with specified device type
+4. Registers with bridge using registerChild()
+5. Bridge adds device to aggregator
+6. On server ready, device subscribes to all events dynamically
+```
+
+### Event System
+- **Input**: Expects Matter.js cluster format (e.g., `{onOff: {onOff: true}}`)
+- **Output**: Emits changes in same format when device state changes
+- **Dynamic Subscription**: Iterates through all clusters and subscribes to `$Changed` events
+
+### Key Differences from Static Approach
+- No separate node for each device type
+- No hardcoded cluster names or attributes
+- All device capabilities discovered at runtime
+- Single codebase handles all Matter device types
+
+## Current Issues & Solutions
+
+### ✅ Issue 4: Video Player Commands Not Implemented (RESOLVED)
+- **Symptom**: Matter.js logs "Throws unimplemented exception" for play/pause/stop/sendKey
+- **Root Cause**: Behaviors with commands require method implementations
+- **Solution**: Dynamically patch ALL behavior prototypes at module load time:
+  - Iterate through all behaviors that have cluster.commands
+  - Add command method implementations before devices are loaded
+  - Each method sends command to Node-RED and returns appropriate response
+```javascript
+// Patch behaviors before loading devices
+Object.values(matterBehaviors).forEach(BehaviorClass => {
+    if (BehaviorClass?.cluster?.commands) {
+        Object.entries(BehaviorClass.cluster.commands).forEach(([cmd, def]) => {
+            BehaviorClass.prototype[cmd] = async function(request) {
+                // Send to Node-RED
+                // Return success
+            };
+        });
+    }
+});
+```
+- **Note**: Video player devices are part of Matter 1.4 spec but may not be supported by all controllers yet.
+
+### ✅ Issue 1: Events Not Firing (RESOLVED)
+- **Symptom**: Matter.js logs showed commands but Node-RED didn't emit messages
+- **Root Cause**: Event properties ending with `$Changed` are not enumerable in Matter.js
+- **Solution**: Subscribe to events based on state attributes instead of iterating event properties
+```javascript
+// Instead of iterating events, use state attributes:
+if (node.device.state && node.device.state[clusterName]) {
+    Object.keys(node.device.state[clusterName]).forEach(attributeName => {
+        const eventName = `${attributeName}$Changed`;
+        if (clusterEvents[eventName]) {
+            clusterEvents[eventName].on(handler);
+        }
+    });
+}
+```
+
+### ✅ Issue 2: Multiple Event Emissions (RESOLVED)
+- **Symptom**: Each HomeKit action triggered 3 identical messages
+- **Root Cause**: `serverReady` event emitted multiple times when devices register
+- **Solution**: Added flag to prevent multiple subscriptions
+```javascript
+if (node.eventsSubscribed) {
+    return; // Prevent duplicate subscriptions
+}
+node.eventsSubscribed = true;
+```
+
+## Code Structure
+
+### Bridge Registration
+```javascript
+// Bridge exposes function
+node.registerChild = function(child) {
+    // Add to registered devices
+    // Add device to aggregator
+    // Start server when ready
+}
+
+// Device calls it
+node.bridge.registerChild(node);
+```
+
+### Dynamic Event Subscription
+```javascript
+// Events ending with $Changed are not enumerable, so we use state attributes
+Object.keys(node.device.events).forEach(clusterName => {
+    if (node.device.state && node.device.state[clusterName]) {
+        Object.keys(node.device.state[clusterName]).forEach(attributeName => {
+            const eventName = `${attributeName}$Changed`;
+            if (node.device.events[clusterName][eventName]) {
+                // Subscribe to state change
+                node.device.events[clusterName][eventName].on((value, oldValue, context) => {
+                    const msg = { payload: {} };
+                    msg.payload[clusterName] = {};
+                    msg.payload[clusterName][attributeName] = value;
+                    node.send(msg);
+                });
+            }
+        });
+    }
+});
+```
+
+### Event Cleanup
+Proper cleanup on node close to prevent memory leaks:
+```javascript
+// Store handlers for cleanup
+node.eventHandlers[`${clusterName}.${eventName}`] = handler;
+
+// On close, remove all event listeners
+for (const [handlerKey, handler] of Object.entries(node.eventHandlers)) {
+    const [clusterName, eventName] = handlerKey.split('.');
+    await node.device.events[clusterName][eventName].off(handler);
+}
+node.removeAllListeners('serverReady');
+```
+
+## Payload Format Examples
+
+### Light Control
+```javascript
+// Input to turn on
+msg.payload = {onOff: {onOff: true}}
+
+// Output when state changes
+msg.payload = {onOff: {onOff: false}}
+```
+
+### Temperature Sensor
+```javascript
+// Input to set temperature (21.5°C)
+msg.payload = {temperatureMeasurement: {measuredValue: 2150}}
+```
+
+## Key Implementation Details
+
+### Event Discovery
+Matter.js events ending with `$Changed` are not enumerable properties. The solution uses the device state to discover available attributes and then checks for corresponding events:
+
+1. Iterate through `node.device.state` clusters
+2. For each attribute in the state, check if `${attribute}$Changed` event exists
+3. Subscribe only to existing events
+
+### Performance Considerations
+- Single event subscription per attribute (prevented by flag)
+- Proper cleanup prevents memory leaks
+- 2-second delay after `serverReady` ensures Matter.js initialization
+
+### ✅ Issue 3: Matter.js Validation Errors Crash Node-RED (RESOLVED)
+- **Symptom**: Node-RED crashes when creating devices with missing mandatory attributes
+- **Root Cause**: Unhandled Promise rejection from Matter.js validation
+- **Solution**: Added unhandled rejection handler in bridge to catch Matter.js errors
+```javascript
+process.on('unhandledRejection', (reason, promise) => {
+    if (reason && reason.message && reason.message.includes('Behaviors have errors')) {
+        // Handle gracefully, mark device as failed
+        // Prevent Node-RED crash
+    }
+});
+```
+
+## Command Handling Architecture
+
+### Dynamic Command Interception
+The system dynamically intercepts ALL commands for ANY device type without hardcoding:
+1. At module load time, patches all behavior prototypes that have commands
+2. Each command method sends message to Node-RED when invoked
+3. Returns appropriate Matter response based on command schema
+4. Works for all current and future device types
+
+### Two-Output System
+Device nodes have two outputs for different message types:
+- **Output 1**: State change events (when attributes change)
+- **Output 2**: Commands received from Matter controllers
+
+This separation allows:
+- Backward compatibility with existing flows using events
+- Clear distinction between state changes and commands
+- Easy routing of different message types
+
+Example messages:
+```javascript
+// Output 1 - Event
+{ onOff: { onOff: true } }
+
+// Output 2 - Command  
+{ command: "on", cluster: "OnOff", data: undefined }
+```
+
+### Controller Support Status
+- **Fully Supported**: Lights, Switches, Sensors, Thermostats, Locks
+- **Limited Support**: 
+  - Video Players (Matter 1.4) - Not recognized by HomeKit/Tuya yet
+  - Advanced features may require specific controller support
+
+## Enhanced Devices Architecture
+
+### Overview
+The system supports creating enhanced devices by adding additional behaviors/clusters to a primary device type using the `additionalBehaviors` configuration.
+
+### Enhanced Device Implementation
+Adds extra functionality to a primary device type:
+```javascript
+{
+  "deviceType": "ThermostatDevice",
+  "additionalBehaviors": ["PowerSourceServer", "RelativeHumidityMeasurementServer"]
+}
+```
+
+### How It Works
+1. **Primary Device Type**: The main device type (e.g., ThermostatDevice)
+2. **Additional Behaviors**: Extra clusters added to the same endpoint
+3. **Behavior Aggregation**: All behaviors are merged into a single endpoint
+4. **Single Endpoint**: Everything runs on one BridgedNodeEndpoint
+
+### Example: Thermostat with Battery and Humidity
+```javascript
+// Configuration
+{
+  "deviceType": "ThermostatDevice",
+  "additionalBehaviors": ["PowerSourceServer", "RelativeHumidityMeasurementServer"],
+  "behaviorFeatures": {
+    "Thermostat": ["Heating", "Cooling"],
+    "PowerSource": ["Battery", "Replaceable"],
+    "RelativeHumidityMeasurement": ["Percentage"]
+  },
+  "initialState": {
+    "thermostat": {
+      "localTemperature": 2000,
+      "systemMode": 4,
+      "occupiedHeatingSetpoint": 2000
+    },
+    "powerSource": {
+      "batPercentRemaining": 100,
+      "batChargeLevel": 1
+    },
+    "relativeHumidityMeasurement": {
+      "measuredValue": 5000
+    }
+  }
+}
+
+// Results in single endpoint with:
+// - ThermostatServer (with Heating/Cooling features)
+// - PowerSourceServer (with Battery features)
+// - RelativeHumidityMeasurementServer
+// - BridgedDeviceBasicInformationServer
+// - IdentifyServer
+```
+
+### Benefits
+- **Simple**: One endpoint manages all functionality
+- **Compatible**: Works with all Matter controllers
+- **Efficient**: No complex child endpoint management
+- **Flexible**: Add only the behaviors you need
+
+### Event Handling
+All events come from the same endpoint:
+```javascript
+// Thermostat event
+{ payload: { thermostat: { localTemperature: 2150 } } }
+
+// Battery event
+{ payload: { powerSource: { batPercentRemaining: 90 } } }
+
+// Humidity event
+{ payload: { relativeHumidityMeasurement: { measuredValue: 6000 } } }
+```
+
+## Next Steps
+
+1. **Add More Examples**: Create comprehensive examples for all device types
+2. **Error Handling**: Better error messages for invalid configurations
+   - **Future Enhancement**: Parse Matter.js validation warnings to show specific missing attributes
+   - Example: Extract `fanModeSequence`, `percentCurrent` from validation logs
+   - Goal: Show user-friendly list of missing mandatory attributes
+3. **Documentation**: Expand user documentation with more device examples
+4. **Testing**: Add automated tests for various device types including composite devices
+5. **Generic Command Handler**: Extend dynamic command handling to all clusters with commands
+
+## Dependencies
+
+- `@matter/main`: Core Matter.js implementation
+- Node-RED >= 3.0.0
+- Node.js >= 18.0.0
+
+## Testing
+
+Current test flow in `examples/flows.json` includes:
+- OnOffLightDevice
+- TemperatureSensorDevice
+
+Both should respond to HomeKit commands and emit state changes to Node-RED.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 faxioman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+AirNexus Node-RED Matter Dynamic
+
+Dynamic Matter bridge + dynamic devices for Node-RED. Create any Matter device by specifying the device type in JSON configuration — no need for device-specific nodes.
+
+This AirNexus fork adds:
+
+Matter Pairing node (get QR/manual codes, reopen pairing, factory reset commissioning)
+
+Matter Device “hidden until enabled” mode (devices don’t appear in Alexa/HomeKit until you enable them by payload)
+
+Dynamic rename by payload
+
+Thermostat-friendly event handling (captures attribute writes even when controllers don’t send explicit commands)
+
+Installation
+npm install @airnexus/node-red-contrib-matter-airnexus
+
+Requirements
+
+Node.js >= 18.0.0
+
+Node-RED >= 3.0.0
+
+Nodes Included
+1) Matter Dynamic Bridge (matter-dynamic-bridge)
+
+Creates a Matter bridge and hosts all devices.
+
+2) Matter Device (matter-device)
+
+Creates a dynamic Matter endpoint from JSON config.
+
+AirNexus behavior (Option 2 – hidden until enabled):
+
+Device is created locally, but NOT registered into the bridge/aggregator until enabled
+
+Once enabled, the device becomes visible in Alexa/HomeKit/Google
+
+Disable sets reachable=false and suppresses outputs (device may remain listed in the controller until you remove it there)
+
+3) Matter Pairing (matter-pairing)
+
+Provides commissioning info (QR/manual) and supports “reset pairing” flows.
+
+Quick Start
+1) Create a Bridge
+
+Add Matter Dynamic Bridge
+
+Configure name/port/interface (default port 5540)
+
+Deploy
+
+2) Get Pairing Codes (recommended: use Matter Pairing node)
+
+Add Matter Pairing
+
+Select your bridge
+
+Deploy
+
+Inject get to output pairing info (QR code string + manual code)
+
+3) Add Devices
+
+Add Matter Device
+
+Select the same bridge
+
+Set your JSON device config (examples below)
+
+Deploy
+
+4) Enable a Device (AirNexus Option 2)
+
+Devices will not show up in Alexa until you enable them:
+
+Inject to the device:
+
+topic: enable
+
+payload can include a name
+
+Example:
+
+{
+  "topic": "enable",
+  "payload": { "name": "Lounge Thermostat" }
+}
+
+Matter Pairing Node
+Inputs (commands)
+
+Send an Inject into the Matter Pairing node:
+
+Command	How to send	What it does
+get	msg.topic="get"	Outputs current pairing info (if commissioned → state=commissioned)
+pair	msg.topic="pair"	Ensures bridge is online and ready to commission (best effort)
+reset	msg.topic="reset"	Factory reset commissioning (wipes bridge commissioning storage, regenerates codes)
+unpair / delete	msg.topic="unpair"	Same as reset
+disable	msg.topic="disable"	Best-effort stop advertising (takes server offline)
+
+Optional payload:
+
+{ "timeoutMins": 15, "includeSvg": true, "forceReset": true }
+
+Output payload (example)
+{
+  "bridgeId": "5318704ab571aeeb",
+  "pairingEnabled": true,
+  "pairingUntil": "2026-01-25T02:30:00.000Z",
+  "state": "ready",
+  "commissioned": false,
+  "qrPairingCode": "MT:....",
+  "manualPairingCode": "123-45-678",
+  "qrSvg": "<svg>...</svg>"
+}
+
+Matter Device Node (AirNexus Option 2: hidden until enabled)
+Enable / Disable / Rename (by payload)
+
+Enable
+
+msg.topic = "enable";
+msg.payload = { name: "Zone 1 Thermostat" }; // optional
+return msg;
+
+
+Disable
+
+msg.topic = "disable";
+return msg;
+
+
+Rename
+
+msg.topic = "name";
+msg.payload = "New Name Here";
+return msg;
+
+
+Config combined
+
+msg.topic = "config";
+msg.payload = { enabled: true, name: "Zone 2 Thermostat" };
+return msg;
+
+State query
+msg.topic = "state";
+return msg;
+
+Inputs / Outputs (Matter Device)
+
+The Matter Device node has 3 outputs:
+
+Output 1 – Events / State
+
+$Changed attribute events (when Matter.js emits them)
+
+Thermostat writes often appear as interactionEnd snapshot diffs (even when no explicit commands are used)
+
+Output 2 – Commands
+
+Real Matter cluster commands (e.g. OnOff.on, LevelControl.moveToLevel)
+
+Some controllers do attribute writes instead of commands (especially thermostats)
+
+Output 3 – Debug / Diagnostics
+
+subscription logs, init status, bridgeReset, write retries, sanitization info, etc.
+
+Example Output 2 (command)
+{
+  "command": "on",
+  "cluster": "OnOff",
+  "data": {}
+}
+
+Example Output 1 (thermostat diff from Alexa)
+{
+  "thermostat": {
+    "systemMode": 3,
+    "occupiedCoolingSetpoint": 2000,
+    "occupiedHeatingSetpoint": 2000
+  }
+}
+
+Command vs Attribute Writes (Thermostats)
+
+Many Matter thermostats are controlled via attribute writes rather than explicit commands.
+
+Typical behavior:
+
+Changing setpoint in Alexa/HomeKit → Output 1 (state diff)
+
+Using something like setpointRaiseLower (if controller uses it) → Output 2 (command)
+
+Always monitor Output 1 for thermostat changes.
+
+Configuration Examples
+Simple On/Off Light
+{
+  "deviceType": "OnOffLightDevice"
+}
+
+Thermostat (Heating + Cooling + Auto)
+{
+  "deviceType": "ThermostatDevice",
+  "behaviorFeatures": {
+    "Thermostat": ["Heating", "Cooling", "AutoMode"]
+  },
+  "initialState": {
+    "thermostat": {
+      "controlSequenceOfOperation": 4,
+      "systemMode": 1,
+      "localTemperature": 2500,
+      "minSetpointDeadBand": 100,
+      "occupiedHeatingSetpoint": 2000,
+      "occupiedCoolingSetpoint": 2600,
+      "minHeatSetpointLimit": 500,
+      "maxHeatSetpointLimit": 3500,
+      "minCoolSetpointLimit": 500,
+      "maxCoolSetpointLimit": 3500
+    }
+  }
+}
+
+Troubleshooting
+Device doesn’t appear in Alexa/HomeKit
+
+If you’re using AirNexus Option 2:
+
+You must enable the Matter Device node:
+
+msg.topic="enable"
+
+optionally set name
+
+Pairing issues / want to re-pair
+
+Use Matter Pairing node:
+
+reset to wipe commissioning + generate new QR/manual
+
+Commands not appearing in Output 2
+
+Expected for devices controlled by attribute writes (thermostats). Use Output 1 diffs.
+
+License
+
+MIT
+
+Acknowledgments
+
+Inspired by and based on patterns from node-red-matter-bridge and Matter.js.
+
+## Support
+
+
+- Node-RED Forum: [Get help from the community](https://discourse.nodered.org)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT
+
+## Acknowledgments
+
+This project was heavily inspired by and based on the excellent work done in [node-red-matter-bridge](https://github.com/sammachin/node-red-matter-bridge) by Sam Machin. The architecture and implementation patterns from that project served as a fundamental guide for developing this dynamic Matter bridge implementation.
+
+Built on top of the excellent [Matter.js](https://github.com/project-chip/matter.js) library.

package/icons/matter-device-icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 115 112">
+  <path d="M85.715 52.905c-7.996 2.19-15.164 7.406-19.636 15.152s-5.407 16.568-3.306 24.587l7.835-4.526a23.9 23.9 0 0 1 1.105-11.836l18.309 10.569 4.303-2.487v-4.967L76.016 68.829a23.92 23.92 0 0 1 9.699-6.879zm-57.108 0v9.045a23.91 23.91 0 0 1 9.699 6.879L20 79.398v4.967l4.303 2.487 18.306-10.569c1.39 3.868 1.726 7.938 1.108 11.836l7.832 4.526c2.101-8.02 1.167-16.841-3.306-24.587A32.52 32.52 0 0 0 28.607 52.905zM57.161 20l-4.303 2.484v21.138c-4.046-.731-7.736-2.476-10.804-4.961l-7.838 4.522c5.895 5.83 14 9.429 22.946 9.429s17.051-3.599 22.946-9.429l-7.835-4.522a23.92 23.92 0 0 1-10.807 4.961V22.484z" fill="#000000"/>
+</svg>