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

package/CHANGELOG.md

@@ -6,6 +6,10 @@
 
 # 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/>

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
     })
 

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

@@ -84,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': {
@@ -292,7 +301,7 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
   // 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') {
+  if (def.type === 'windowcovering' && def.coverExposeAsDimmableLight !== true) {
     initialState.windowCovering = {
       currentPositionLiftPercent100ths: 0,
       targetPositionLiftPercent100ths: 0
@@ -331,6 +340,48 @@ function createBridgedEndpoint (def, serialPrefix, onCommand) {
     }
   }
 
+  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

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