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

package/CHANGELOG.md

@@ -6,6 +6,15 @@
 
 # CHANGELOG
 
+**Version 6.0.3** - July 2026<br/>
+
+- **Expose KNX to Matter (BETA) — Alexa cover percentage workaround**: covers/shutters can optionally be exposed to Matter controllers as dimmable lights when Alexa does not send percentage commands to a native Window Covering endpoint. Brightness represents openness (`100%` open, `0%` closed), while On/Off opens or closes the cover. Commands and status remain mapped through the existing KNX cover position GA/DPT, including position inversion and loop-protected KNX-to-Matter feedback. The standard Matter Window Covering endpoint remains the default.<br/>
+
+**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.html

@@ -75,6 +75,7 @@
       name: { value: '' },
       deviceType: { value: 'onofflight' },
       invertPosition: { value: false },
+      coverExposeAsDimmableLight: { value: false },
       turnOnBehavior: { value: 'ignoreLevelAfterOn' },
       ignoreLevelAfterOnMs: { value: 800 },
       coverUpdateMode: { value: 'optimistic' },
@@ -228,6 +229,7 @@
         node._matterGaInputs = gaInputs;
 
         $('#node-input-invertPosition').prop('checked', node.invertPosition === true);
+        $('#node-input-coverExposeAsDimmableLight').prop('checked', node.coverExposeAsDimmableLight === true);
         $('#node-input-turnOnBehavior').val(node.turnOnBehavior || 'ignoreLevelAfterOn');
         $('#node-input-ignoreLevelAfterOnMs').val(node.ignoreLevelAfterOnMs === undefined ? 800 : node.ignoreLevelAfterOnMs);
         $('#node-input-coverUpdateMode').val(node.coverUpdateMode || 'optimistic');
@@ -241,6 +243,7 @@
         const selected = $('#node-input-deviceType').val();
         node.deviceType = selected;
         node.invertPosition = $('#node-input-invertPosition').is(':checked');
+        node.coverExposeAsDimmableLight = selected === 'windowcovering' && $('#node-input-coverExposeAsDimmableLight').is(':checked');
         const active = TYPE_FIELDS[selected] || [];
         const gaInputs = node._matterGaInputs || {};
         // Clear every GA/DPT, then write only the ones of the selected type, reading
@@ -346,6 +349,14 @@
       <input type="number" id="node-input-ignoreLevelAfterOnMs" min="0" step="100" style="width:120px;">
     </div>
 
+    <div class="form-row mb-cover-advanced-row" style="display:none; margin-top:8px;">
+      <label for="node-input-coverExposeAsDimmableLight" style="width:auto;">
+        <input type="checkbox" id="node-input-coverExposeAsDimmableLight" style="width:auto; display:inline-block; vertical-align:middle;">
+        <span data-i18n="knxUltimateMatterBridge.advanced.cover_expose_as_light"></span>
+      </label>
+      <div class="form-tips" style="margin-top:5px;" data-i18n="knxUltimateMatterBridge.advanced.cover_expose_as_light_help"></div>
+    </div>
+
     <div class="form-row mb-cover-advanced-row" style="display:none; margin-top:8px;">
       <label for="node-input-coverUpdateMode" style="width:260px;">
         <i class="fa fa-window-maximize"></i> <span data-i18n="knxUltimateMatterBridge.advanced.cover_update_mode"></span>
@@ -406,6 +417,7 @@ The advanced compatibility options are intentionally type-specific:
 
 - dimmable devices can ignore the brightness command that some controllers send immediately after an On command
 - covers can optimistically update the Matter position after a command, then correct it when the KNX status GA reports the real position
+- if Alexa cannot set a cover percentage, a cover can be exposed as a dimmable light: brightness means openness, while the configured KNX cover GAs and DPTs remain unchanged
 
 The **KNX gateway is optional**: without it, enable the node PINs and drive the device from the flow.
 
@@ -413,4 +425,4 @@ If you enable the **node PINs**:
 
 - input: `msg.payload = { function: "onoff", value: true }` updates the Matter state without the KNX bus
 - output: every command from a Matter controller is forwarded as `msg` (topic = device name, payload = value, `msg.matter` = raw command)
-</script>
+</script>

package/nodes/knxUltimateMatterBridge.js

@@ -77,6 +77,7 @@ module.exports = function (RED) {
     // The Matter device id is the (stable) Node-RED node id, so the endpoint survives re-deploys.
     node.matterDeviceId = node.id
     node.invertPosition = config.invertPosition === true || config.invertPosition === 'true'
+    node.coverExposeAsDimmableLight = config.coverExposeAsDimmableLight === true || config.coverExposeAsDimmableLight === 'true'
     node.turnOnBehavior = config.turnOnBehavior || 'ignoreLevelAfterOn'
     node.ignoreLevelAfterOnMs = Number(config.ignoreLevelAfterOnMs)
     if (!Number.isFinite(node.ignoreLevelAfterOnMs) || node.ignoreLevelAfterOnMs < 0) node.ignoreLevelAfterOnMs = 800
@@ -203,6 +204,7 @@ module.exports = function (RED) {
       type: node.deviceType,
       name: node.name,
       invertPosition: node.invertPosition === true,
+      coverExposeAsDimmableLight: node.coverExposeAsDimmableLight === true,
       coverUpdateMode: node.coverUpdateMode
     })
 
@@ -227,6 +229,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/locales/de/knxUltimateMatterBridge.json

@@ -23,7 +23,9 @@
       "turn_on_behavior": "Einschaltverhalten",
       "turn_on_ignore_level": "Helligkeit direkt nach Ein ignorieren",
       "turn_on_forward_all": "Jeden Helligkeitsbefehl weiterleiten",
-      "ignore_level_ms": "Helligkeit nach Ein ignorieren (ms)",
+    "ignore_level_ms": "Helligkeit nach Ein ignorieren (ms)",
+    "cover_expose_as_light": "Rollladen als dimmbares Licht anzeigen (Alexa-Workaround)",
+    "cover_expose_as_light_help": "Nur verwenden, wenn Alexa die Rollladenposition nicht einstellen kann. Die Helligkeit entspricht der Öffnung; die KNX-Gruppenadressen bleiben unverändert.",
       "cover_update_mode": "Jalousie-/Rollladenstatus",
       "cover_optimistic": "Matter-Position optimistisch aktualisieren",
       "cover_wait_status": "Nur auf KNX-Status warten",

package/nodes/locales/en/knxUltimateMatterBridge.json

@@ -23,7 +23,9 @@
       "turn_on_behavior": "Turn-on behavior",
       "turn_on_ignore_level": "Ignore brightness sent immediately after On",
       "turn_on_forward_all": "Forward every brightness command",
-      "ignore_level_ms": "Ignore brightness after On (ms)",
+    "ignore_level_ms": "Ignore brightness after On (ms)",
+    "cover_expose_as_light": "Expose cover as a dimmable light (Alexa workaround)",
+    "cover_expose_as_light_help": "Use only if Alexa cannot set the cover percentage. Brightness represents how open the cover is; KNX group addresses remain unchanged.",
       "cover_update_mode": "Cover state update",
       "cover_optimistic": "Optimistically update Matter position",
       "cover_wait_status": "Wait for KNX status only",

package/nodes/locales/es/knxUltimateMatterBridge.json

@@ -23,7 +23,9 @@
       "turn_on_behavior": "Comportamiento al encender",
       "turn_on_ignore_level": "Ignorar brillo enviado justo después de On",
       "turn_on_forward_all": "Reenviar cada comando de brillo",
-      "ignore_level_ms": "Ignorar brillo tras On (ms)",
+    "ignore_level_ms": "Ignorar brillo tras On (ms)",
+    "cover_expose_as_light": "Exponer persiana como luz regulable (solución para Alexa)",
+    "cover_expose_as_light_help": "Úsalo solo si Alexa no puede ajustar el porcentaje de la persiana. El brillo representa cuánto está abierta; las direcciones de grupo KNX no cambian.",
       "cover_update_mode": "Actualización de estado de persiana",
       "cover_optimistic": "Actualizar la posición Matter de forma optimista",
       "cover_wait_status": "Esperar solo el estado KNX",

package/nodes/locales/fr/knxUltimateMatterBridge.json

@@ -23,7 +23,9 @@
       "turn_on_behavior": "Comportement à l'allumage",
       "turn_on_ignore_level": "Ignorer la luminosité envoyée juste après On",
       "turn_on_forward_all": "Transmettre chaque commande de luminosité",
-      "ignore_level_ms": "Ignorer la luminosité après On (ms)",
+    "ignore_level_ms": "Ignorer la luminosité après On (ms)",
+    "cover_expose_as_light": "Exposer le volet comme lumière variable (contournement Alexa)",
+    "cover_expose_as_light_help": "À utiliser seulement si Alexa ne règle pas le pourcentage du volet. La luminosité représente son ouverture ; les adresses de groupe KNX restent inchangées.",
       "cover_update_mode": "Mise à jour état volet",
       "cover_optimistic": "Mettre à jour la position Matter de façon optimiste",
       "cover_wait_status": "Attendre seulement l'état KNX",

package/nodes/locales/it/knxUltimateMatterBridge.json

@@ -23,7 +23,9 @@
       "turn_on_behavior": "Comportamento all'accensione",
       "turn_on_ignore_level": "Ignora luminosità inviata subito dopo On",
       "turn_on_forward_all": "Inoltra ogni comando luminosità",
-      "ignore_level_ms": "Ignora luminosità dopo On (ms)",
+    "ignore_level_ms": "Ignora luminosità dopo On (ms)",
+    "cover_expose_as_light": "Esponi tapparella come luce dimmerabile (workaround Alexa)",
+    "cover_expose_as_light_help": "Usa questa opzione solo se Alexa non imposta la percentuale della tapparella. La luminosità indica quanto è aperta; gli indirizzi di gruppo KNX non cambiano.",
       "cover_update_mode": "Aggiornamento stato tapparella",
       "cover_optimistic": "Aggiorna ottimisticamente la posizione Matter",
       "cover_wait_status": "Attendi solo lo stato KNX",

package/nodes/locales/zh-CN/knxUltimateMatterBridge.json

@@ -23,7 +23,9 @@
       "turn_on_behavior": "开灯行为",
       "turn_on_ignore_level": "忽略 On 后立即发送的亮度",
       "turn_on_forward_all": "转发每个亮度命令",
-      "ignore_level_ms": "On 后忽略亮度时间 (ms)",
+    "ignore_level_ms": "On 后忽略亮度时间 (ms)",
+    "cover_expose_as_light": "将窗帘显示为可调光灯（Alexa 兼容方案）",
+    "cover_expose_as_light_help": "仅当 Alexa 无法设置窗帘百分比时使用。亮度表示窗帘开启程度；KNX 组地址保持不变。",
       "cover_update_mode": "窗帘状态更新",
       "cover_optimistic": "乐观更新 Matter 位置",
       "cover_wait_status": "仅等待 KNX 状态",

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'
@@ -82,6 +84,15 @@ function knxValueToMatterPatch (def, fn, value) {
       let percent = Number(value)
       if (Number.isNaN(percent)) return undefined
       if (def.invertPosition === true) percent = 100 - percent
+      if (def.type === 'windowcovering' && def.coverExposeAsDimmableLight === true) {
+        // Alexa compatibility mode: light brightness represents how open the cover is.
+        // Keep the KNX convention at this boundary and invert only the Matter view.
+        const openness = clamp(100 - percent, 0, 100)
+        return {
+          onOff: { onOff: openness > 0 },
+          levelControl: { currentLevel: clamp(Math.round(openness * 254 / 100), 1, 254) }
+        }
+      }
       return { windowCovering: { currentPositionLiftPercent100ths: clamp(Math.round(percent * 100), 0, 10000) } }
     }
     case 'rgb': {
@@ -287,9 +298,90 @@ 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' && def.coverExposeAsDimmableLight !== true) {
+    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' && def.coverExposeAsDimmableLight === true) {
+    const invert = def.invertPosition === true
+    const emitPosition = (matterPosition, command, request) => {
+      let position = clamp(Math.round(matterPosition), 0, 100)
+      if (invert) position = 100 - position
+      onCommand({
+        deviceId: def.id,
+        fn: 'position',
+        value: position,
+        matterCommand: { cluster: command === 'on' || command === 'off' ? 'OnOff' : 'LevelControl', command, request },
+        matterDiagnostic: { handler: 'coverAsDimmableLight', command }
+      })
+    }
+
+    class CoverAsLightOnOffServer extends OnOffServer.with('Lighting') {
+      async on () {
+        await super.on()
+        emitPosition(0, 'on')
+      }
+
+      async off () {
+        await super.off()
+        emitPosition(100, 'off')
+      }
+    }
+
+    class CoverAsLightLevelServer extends LevelControlServer.with('Lighting', 'OnOff') {
+      async moveToLevel (request) {
+        await super.moveToLevel(request)
+        emitPosition(100 - clamp(Number(request.level) * 100 / 254, 0, 100), 'moveToLevel', request)
+      }
+
+      async moveToLevelWithOnOff (request) {
+        await super.moveToLevelWithOnOff(request)
+        emitPosition(100 - clamp(Number(request.level) * 100 / 254, 0, 100), 'moveToLevelWithOnOff', request)
+      }
+    }
+
+    endpoint = new Endpoint(DimmableLightDevice.with(CoverAsLightOnOffServer, CoverAsLightLevelServer, BridgedDeviceBasicInformationServer), initialState)
+    return endpoint
+  }
+
   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 +391,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 +460,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 +472,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 +589,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/nodes/utils/matterBridgeEngine.mjs

@@ -169,7 +169,9 @@ class classMatterBridge extends EventEmitter {
       const newDef = newById.get(id)
       const oldDef = this.deviceDefs.get(id)
       const needsRecreate = newDef !== undefined && oldDef !== undefined &&
-        (newDef.type !== oldDef.type || (newDef.invertPosition === true) !== (oldDef.invertPosition === true))
+        (newDef.type !== oldDef.type ||
+          (newDef.invertPosition === true) !== (oldDef.invertPosition === true) ||
+          (newDef.coverExposeAsDimmableLight === true) !== (oldDef.coverExposeAsDimmableLight === true))
       if (newDef === undefined || needsRecreate) {
         await this.removeDeviceEndpoint(id)
       }

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.0.1",
+  "version": "6.0.3",
   "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/",