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

package/CHANGELOG.md

@@ -6,6 +6,15 @@
 
 # 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/>
+
 **Version 6.0.0** - July 2026<br/>
 
 - **BREAKING CHANGE**: this release intentionally bumps the package to `6.0.0` because the Matter node model changed. The unpublished dedicated Matter controller nodes and the old generic Matter Device node have been replaced by the new single **Control Matter from KNX (BETA)** node, and the KNX-to-Matter bridge/editor behaviour has been reworked. Existing experimental Matter flows created with the previous beta nodes may need to be rebuilt or adjusted.<br/>

package/nodes/knxUltimateMatterBridge.js

@@ -179,6 +179,22 @@ module.exports = function (RED) {
       }
       return false
     }
+
+    const applyOptimisticCoverPosition = (command) => {
+      if (node.deviceType !== 'windowcovering' || node.coverUpdateMode !== 'optimistic' || !node.serverMatterBridge) return
+      let optimisticPosition
+      if (command.fn === 'position') optimisticPosition = command.value
+      if (command.fn === 'updown') optimisticPosition = command.value === true ? 100 : 0
+      if (optimisticPosition === undefined) return
+      node.serverMatterBridge.setDeviceState(node.matterDeviceId, 'position', optimisticPosition)
+      clearCoverStatusTimer()
+      if (node.coverStatusTimeoutMs > 0 && hasStatusRouteFor('position')) {
+        coverStatusTimer = setTimeout(() => {
+          coverStatusTimer = null
+          node.setNodeStatus({ fill: 'yellow', shape: 'ring', text: 'Waiting for KNX cover status', payload: optimisticPosition })
+        }, node.coverStatusTimeoutMs)
+      }
+    }
     node.knxUltimateAcceptedGAs = Array.from(statusRoutes.keys())
 
     // The device definition consumed by the bridge engine (via the config node).
@@ -211,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({
@@ -221,6 +244,9 @@ module.exports = function (RED) {
             })
           } catch (error) { /* empty */ }
         }
+        // Confirm the requested position to Matter even when this is a flow-only
+        // device and no KNX command GA is configured.
+        applyOptimisticCoverPosition(command)
         const route = commandRoutes.get(command.fn)
         if (route === undefined) {
           if (node.enableNodePINS) return // Flow-only device: the flow already got the command
@@ -240,21 +266,6 @@ module.exports = function (RED) {
           return
         }
         safeSendToKNX({ grpaddr: route.ga, payload: command.value, dpt: route.dpt, outputtype: 'write' }, 'write')
-        if (node.deviceType === 'windowcovering' && node.coverUpdateMode === 'optimistic' && node.serverMatterBridge) {
-          let optimisticPosition
-          if (command.fn === 'position') optimisticPosition = command.value
-          if (command.fn === 'updown') optimisticPosition = command.value === true ? 100 : 0
-          if (optimisticPosition !== undefined) {
-            node.serverMatterBridge.setDeviceState(node.matterDeviceId, 'position', optimisticPosition)
-            clearCoverStatusTimer()
-            if (node.coverStatusTimeoutMs > 0 && hasStatusRouteFor('position')) {
-              coverStatusTimer = setTimeout(() => {
-                coverStatusTimer = null
-                node.setNodeStatus({ fill: 'yellow', shape: 'ring', text: 'Waiting for KNX cover status', payload: optimisticPosition })
-              }, node.coverStatusTimeoutMs)
-            }
-          }
-        }
         node.setNodeStatus({ fill: 'green', shape: 'dot', text: `Matter->KNX ${command.fn}`, payload: command.value })
       } catch (error) {
         node.setNodeStatus({ fill: 'red', shape: 'dot', text: `Matter->KNX error ${error.message}` })

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.0",
+  "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/",