node-red-contrib-knx-ultimate 6.0.1 → 6.0.2

package/CHANGELOG.md

@@ -6,6 +6,11 @@
 
 # CHANGELOG
 
+**Version 6.0.2** - July 2026<br/>
+
+- **Expose KNX to Matter (BETA) — covers/shutters with Alexa**: initialize position-aware covers with a valid numeric Matter position instead of an unknown (`null`) value. This helps controllers such as Alexa expose percentage positioning and send `GoToLiftPercentage` instead of degrading to Open/Close only. Added targeted command diagnostics to the Node-RED log and output message for interoperability testing.<br/>
+- **Expose KNX to Matter (BETA) — raw flow output**: On/Off and absolute dimming commands are now captured at the Matter command boundary, so the optional output PIN forwards repeated commands even when the Matter state is already unchanged. Matter validation still runs before KNX routing, and KNX-to-Matter status updates remain loop-protected.<br/>
+
 **Version 6.0.1** - July 2026<br/>
 
 - **Expose KNX to Matter (BETA) — flow-only covers/shutters**: fixed intermediate position commands reaching the Node-RED output but not being optimistically confirmed to Matter when no KNX command group address was configured. Voice assistants such as Alexa no longer report that the device is not responding after a percentage-position command.<br/>

package/nodes/knxUltimateMatterBridge.js

@@ -227,6 +227,13 @@ module.exports = function (RED) {
     // Matter -> KNX: a controller (Alexa...) sent a command to this device.
     node.handleMatterCommand = (command) => {
       try {
+        if (node.deviceType === 'windowcovering' && command.matterDiagnostic && typeof node.log === 'function') {
+          node.log(`Matter WindowCovering command: ${JSON.stringify({
+            fn: command.fn,
+            value: command.value,
+            ...command.matterDiagnostic
+          })}`)
+        }
         if (node.enableNodePINS) {
           try {
             node.send({

package/nodes/utils/matterBridgeDeviceFactory.mjs

@@ -3,6 +3,8 @@
 // Each KNX "virtual device" definition becomes a Matter endpoint under the aggregator.
 import { Endpoint } from '@matter/main'
 import { BridgedDeviceBasicInformationServer } from '@matter/main/behaviors/bridged-device-basic-information'
+import { OnOffServer } from '@matter/main/behaviors/on-off'
+import { LevelControlServer } from '@matter/main/behaviors/level-control'
 import { OnOffLightDevice } from '@matter/main/devices/on-off-light'
 import { DimmableLightDevice } from '@matter/main/devices/dimmable-light'
 import { OnOffPlugInUnitDevice } from '@matter/main/devices/on-off-plug-in-unit'
@@ -287,9 +289,48 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
   // Non nullable attributes need a sane initial value
   if (def.type === 'contactsensor') initialState.booleanState = { stateValue: false }
   if (def.type === 'occupancysensor') initialState.occupancySensing = { occupancy: { occupied: false } }
+  // Although Matter permits an unknown (null) position, some controllers (including
+  // Alexa) then expose only Open/Close instead of percentage positioning. Start with
+  // a valid position; KNX or flow feedback replaces it as soon as it is available.
+  if (def.type === 'windowcovering') {
+    initialState.windowCovering = {
+      currentPositionLiftPercent100ths: 0,
+      targetPositionLiftPercent100ths: 0
+    }
+  }
 
   let endpoint
 
+  // Emit controller commands at the command boundary instead of observing attribute
+  // changes. This makes the node output truly raw: repeated commands (for example
+  // Off while already off) are still forwarded exactly once.
+  const RawOnOffBase = def.type === 'onoffplug' ? OnOffServer : OnOffServer.with('Lighting')
+  class RawOnOffServer extends RawOnOffBase {
+    async on () {
+      await super.on()
+      onCommand({ deviceId: def.id, fn: 'onoff', value: true, matterCommand: { cluster: 'OnOff', command: 'on' } })
+    }
+
+    async off () {
+      await super.off()
+      onCommand({ deviceId: def.id, fn: 'onoff', value: false, matterCommand: { cluster: 'OnOff', command: 'off' } })
+    }
+  }
+
+  class RawLevelControlServer extends LevelControlServer.with('Lighting', 'OnOff') {
+    async moveToLevel (request) {
+      await super.moveToLevel(request)
+      const value = clamp(Math.round(Number(request.level) * 100 / 254), 0, 100)
+      onCommand({ deviceId: def.id, fn: 'level', value, matterCommand: { cluster: 'LevelControl', command: 'moveToLevel', request } })
+    }
+
+    async moveToLevelWithOnOff (request) {
+      await super.moveToLevelWithOnOff(request)
+      const value = clamp(Math.round(Number(request.level) * 100 / 254), 0, 100)
+      onCommand({ deviceId: def.id, fn: 'level', value, matterCommand: { cluster: 'LevelControl', command: 'moveToLevelWithOnOff', request } })
+    }
+  }
+
   if (def.type === 'windowcovering') {
     // The WindowCoveringServer requires the movement logic: we forward it to the KNX bus.
     // Position feedback comes back from the KNX status GA, so we do NOT call the default
@@ -299,20 +340,35 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
       async handleMovement (type, reversed, direction, targetPercent100ths) {
         try {
           if (type !== MovementType.Lift) return
+          const matterDiagnostic = {
+            handler: 'handleMovement',
+            movementType: type,
+            reversed: reversed === true,
+            direction,
+            directionName: direction === MovementDirection.DefinedByPosition
+              ? 'DefinedByPosition'
+              : direction === MovementDirection.Open ? 'Open' : direction === MovementDirection.Close ? 'Close' : 'Unknown',
+            targetPercent100ths: targetPercent100ths ?? null
+          }
           if (direction === MovementDirection.DefinedByPosition && targetPercent100ths !== undefined && targetPercent100ths !== null) {
             let percent = Math.round(Number(targetPercent100ths) / 100)
             if (invert) percent = 100 - percent
-            onCommand({ deviceId: def.id, fn: 'position', value: clamp(percent, 0, 100) })
+            onCommand({ deviceId: def.id, fn: 'position', value: clamp(percent, 0, 100), matterDiagnostic })
           } else if (direction === MovementDirection.Open || direction === MovementDirection.Close) {
             // KNX DPT 1.008: 0 = up/open, 1 = down/close
-            onCommand({ deviceId: def.id, fn: 'updown', value: direction === MovementDirection.Close })
+            onCommand({ deviceId: def.id, fn: 'updown', value: direction === MovementDirection.Close, matterDiagnostic })
           }
         } catch (error) { /* empty */ }
       }
 
       async handleStopMovement () {
         try {
-          onCommand({ deviceId: def.id, fn: 'stop', value: true })
+          onCommand({
+            deviceId: def.id,
+            fn: 'stop',
+            value: true,
+            matterDiagnostic: { handler: 'handleStopMovement' }
+          })
         } catch (error) { /* empty */ }
         return super.handleStopMovement()
       }
@@ -353,7 +409,7 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
       currentX: Math.round(0.31 * 65536),
       currentY: Math.round(0.33 * 65536)
     }
-    endpoint = new Endpoint(ExtendedColorLightDevice.with(ColorControlServer.with('HueSaturation', 'Xy'), BridgedDeviceBasicInformationServer), initialState)
+    endpoint = new Endpoint(ExtendedColorLightDevice.with(RawOnOffServer, RawLevelControlServer, ColorControlServer.with('HueSaturation', 'Xy'), BridgedDeviceBasicInformationServer), initialState)
     attachColorTracker(endpoint, def, onCommand)
   } else if (def.type === 'colortemperaturelight') {
     initialState.colorControl = {
@@ -365,7 +421,7 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
       startUpColorTemperatureMireds: 250,
       coupleColorTempToLevelMinMireds: 153
     }
-    endpoint = new Endpoint(ColorTemperatureLightDevice.with(ColorControlServer.with('ColorTemperature'), BridgedDeviceBasicInformationServer), initialState)
+    endpoint = new Endpoint(ColorTemperatureLightDevice.with(RawOnOffServer, RawLevelControlServer, ColorControlServer.with('ColorTemperature'), BridgedDeviceBasicInformationServer), initialState)
     endpoint.events.colorControl.colorTemperatureMireds$Changed.on((value, oldValue, context) => {
       try {
         if (context?.offline === true) return
@@ -482,27 +538,10 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
       } catch (error) { /* empty */ }
     })
   } else {
-    endpoint = new Endpoint(typeInfo.device.with(BridgedDeviceBasicInformationServer), initialState)
-  }
-
-  // Matter -> KNX: react only to real controller interactions (context.offline is true
-  // for state changes we apply ourselves via endpoint.set(), which must NOT loop back to KNX).
-  if (typeInfo.commandFunctions.includes('onoff')) {
-    endpoint.events.onOff.onOff$Changed.on((value, oldValue, context) => {
-      try {
-        if (context?.offline === true) return
-        onCommand({ deviceId: def.id, fn: 'onoff', value: value === true })
-      } catch (error) { /* empty */ }
-    })
-  }
-  if (typeInfo.commandFunctions.includes('level')) {
-    endpoint.events.levelControl.currentLevel$Changed.on((value, oldValue, context) => {
-      try {
-        if (context?.offline === true) return
-        if (value === null || value === undefined) return
-        onCommand({ deviceId: def.id, fn: 'level', value: clamp(Math.round(Number(value) * 100 / 254), 0, 100) })
-      } catch (error) { /* empty */ }
-    })
+    let device = typeInfo.device
+    if (typeInfo.commandFunctions.includes('onoff')) device = device.with(RawOnOffServer)
+    if (typeInfo.commandFunctions.includes('level')) device = device.with(RawLevelControlServer)
+    endpoint = new Endpoint(device.with(BridgedDeviceBasicInformationServer), initialState)
   }
 
   return endpoint

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.0.1",
+  "version": "6.0.2",
   "description": "Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control, ETS group address importer, KNX AI for diagnosticsand KNX routing between interfaces. Easy to use and highly configurable.",
   "files": [
     "nodes/",