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

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

@@ -0,0 +1,89 @@
+{
+  "knxUltimateMatterControllerDevice": {
+    "title": "从 KNX 控制 Matter",
+    "node-input-name": "Name",
+    "node-input-nameLightSwitch": "Switch (bit)",
+    "node-input-GALightSwitch": "GA",
+    "node-input-dptLightSwitch": "dpt",
+    "node-input-nameLightState": "State (bit)",
+    "node-input-GALightState": "GA",
+    "node-input-dptLightState": "dpt",
+    "node-input-hueLight": "Matter 设备",
+    "paletteLabel": "从 KNX 控制 Matter",
+    "no_devices": "未找到 Matter 设备。请检查 Matter 控制器并点击刷新。",
+    "tabs": {
+      "switch": "开关",
+      "dim": "调光",
+      "tunable_white": "可调白光",
+      "rgb_hsv": "RGB/HSV",
+      "effects": "效果",
+      "behaviour": "行为"
+    },
+    "control": "控制",
+    "status": "状态",
+    "night_lighting": "夜间照明",
+    "no_night_lighting": "无夜间照明",
+    "get_current": "获取当前",
+    "get_again": "再次获取",
+    "wait": "请稍候...",
+    "day_night": "昼/夜",
+    "invert_day_night": "反转昼/夜值",
+    "override_night_mode": "强制日间模式",
+    "override_no": "否",
+    "override_set_day_fast_this": "快速关开切换到白天模式（仅此灯）",
+    "override_set_day_fast_all": "快速关开切换到白天模式（应用于所有灯）",
+    "node_pins": "节点输入/输出引脚",
+    "node_pins_hide": "隐藏",
+    "node_pins_show": "显示输入/输出引脚",
+    "read_status_startup": "启动时读取状态",
+    "opt_no": "否",
+    "opt_yes_emit": "是，并发送 KNX 电报。",
+    "knx_brightness_status": "KNX 亮度状态",
+    "knx_brightness_onhueoff": "当 HUE 灯关闭时发送 0%。当 HUE 打开时恢复先前值（默认 KNX 行为）",
+    "knx_brightness_no": "保持不变（默认 HUE 行为）",
+    "update_local_state_from_knx_write": "根据 KNX 总线写入更新本地缓存的 Hue 状态",
+    "update_local_state_from_knx_write_hint": "启用：本地响应更快，KNX 即时读回更一致。禁用：缓存只根据 Hue 网关的真实事件更新。",
+    "use_min_brightness": "使用 HUE 灯中设置的最小亮度",
+    "k_suffix": "K",
+    "temp_desc_2200": "（飞利浦 White Ambiance 系列起始）",
+    "temp_desc_2700": "（暖白，温馨、舒适、私密，适合客厅）",
+    "temp_desc_3000": "（柔和白，温暖、平静，适合浴室和厨房）",
+    "temp_desc_3500_day": "（中性白，均衡、友好、亲切，适合办公室和零售）",
+    "temp_desc_3500_night": "（夜间不推荐——中性白，适合办公室和零售）",
+    "temp_desc_4100_day": "（冷白，精准、干净、聚焦，适合车库和超市）",
+    "temp_desc_4100_night": "（夜间不推荐——冷白，精准、干净、聚焦，适合车库和超市）",
+    "temp_desc_5000_day": "（明亮白，鲜明、清晰，适合仓库、体育场和医疗）",
+    "temp_desc_5000_night": "（夜间不推荐——明亮白，鲜明、清晰，适合仓库、体育场和医疗）",
+    "temp_desc_6500_day": "（日光，警觉、充满活力，适合室内农业）",
+    "temp_desc_6500_night": "（夜间不推荐——日光，警觉、充满活力，适合室内农业）",
+    "switch_on_behaviour": "开灯行为",
+    "none": "无",
+    "switch_off": "(关)",
+    "select_color": "选择颜色",
+    "select_temperature_brightness": "选择色温和亮度",
+    "select_brightness": "选择亮度",
+    "effect_command": "效果命令",
+    "effect_status": "效果状态",
+    "effect_mapping": "映射",
+    "effect_autofill": "填充可用效果",
+    "effect_tip": "配置 KNX 数值与 Hue 效果对，收到匹配的 KNX 数值时触发对应效果。",
+    "effect_tip_status": "若配置状态组地址，将把当前效果（映射值或效果名称）发送到 KNX。",
+    "effect_not_supported": "该灯具不支持 Hue 效果。",
+    "effect_knx_value_placeholder": "匹配值",
+    "effect_base_label": "非 Hue 基础效果",
+    "effect_native_label": "Hue 原生效果",
+    "matter_controller": "Matter 控制器",
+    "matter_device": "Matter 设备",
+    "matter_section": "Matter 设备"
+  },
+  "common": {
+    "ga": "组地址",
+    "dpt": "数据点类型",
+    "name": "名称",
+    "youtube_sample": "YouTube 示例",
+    "knx_gw": "KNX 网关",
+    "hue_bridge": "Hue Bridge",
+    "philips_hue": "飞利浦 HUE",
+    "read": "读取"
+  }
+}

package/nodes/locales/zh-CN/matter-config.json

@@ -8,6 +8,7 @@
       "pairing_title": "配对新设备",
       "pairing_help": "输入 11 位手动配对码（例如 3497-011-2332）或二维码内容（MT:....）。设备必须可通过 IP 网络访问（WiFi/以太网或通过边界路由器的 Thread）。如果设备已与其他控制器（Alexa、Google、Apple）配对，请使用其\"与其他中枢共享/配对\"功能获取新的配对码。",
       "pairing_code": "配对码",
+      "pairing_name": "设备名称",
       "pair_button": "配对",
       "devices_title": "已配对设备",
       "col_name": "名称",
@@ -20,7 +21,10 @@
       "pairing_code_missing": "请输入配对码。",
       "pairing_wait": "正在配对，最多可能需要一分钟...",
       "pairing_failed": "配对失败",
-      "pairing_ok": "设备配对成功！"
+      "pairing_ok": "设备配对成功！",
+      "rename_button": "重命名",
+      "rename_prompt": "新的设备名称",
+      "rename_ok": "设备已重命名。"
     }
   }
 }

package/nodes/locales/zh-CN/matterbridge-config.json

@@ -10,6 +10,7 @@
       "pairing_title": "配对（Alexa、Google Home、Apple Home...）",
       "not_running": "Matter 桥接器尚未运行。请先部署，等待几秒后点击刷新。",
       "commissioned": "桥接器已与以下控制器配对：",
+      "commissioned_hint": "二维码已隐藏，因为桥接器已经配对。若要将 Alexa 添加为另一个 Matter 控制器，请先从上方已配对的控制器之一（例如 Apple Home 或 Google Home）打开配对模式，然后在 Alexa 中添加 Matter 设备。只有在要移除所有现有控制器并重新开始时，才使用重置配对。",
       "awaiting": "等待配对。请在您的 Matter App 中扫描二维码或输入手动配对码：",
       "qr_link": "在浏览器中打开二维码",
       "deploy_first": "请先部署此配置节点，然后点击刷新。",

package/nodes/matter-config.html

@@ -16,10 +16,21 @@
             var node = this;
             var $pairButton = $("#matterPairButton");
             var $pairingCode = $("#matter-pairing-code");
+            var $pairingName = $("#matter-pairing-name");
             var $devicesBody = $("#matter-devices-body");
             var $refreshDevices = $("#matterRefreshDevices");
             var $pairSpinner = $("#matterPairSpinner");
 
+            function notifyPairingError(msg) {
+                var text = RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_failed") + ': ' + (msg || '');
+                try { console.error('[matter-config] ' + text); } catch (error) { }
+                RED.notify(text, {
+                    type: 'error',
+                    fixed: true,
+                    modal: false
+                });
+            }
+
             function renderDevices(devices) {
                 $devicesBody.empty();
                 if (!Array.isArray(devices) || devices.length === 0) {
@@ -33,6 +44,27 @@
                     $tr.append($('<td></td>').text((dev.vendorName || '') + (dev.productName ? ' ' + dev.productName : '')));
                     $tr.append($('<td style="font-family:monospace;"></td>').text(dev.nodeId));
                     $tr.append($('<td></td>').append($('<span></span>').css('color', stateColor).text(dev.connectionState)));
+                    var $rename = $('<button type="button" class="red-ui-button" style="margin-right:6px; color:#1b7d33; border-color:#1b7d33;" title="' + (RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.rename_button") || 'Rename') + '"><i class="fa fa-pencil"></i></button>');
+                    $rename.on('click', function () {
+                        var currentName = dev.name || '';
+                        var promptMsg = RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.rename_prompt") || 'New device name';
+                        var newName = window.prompt(promptMsg, currentName);
+                        if (newName === null) return;
+                        newName = (newName || '').trim();
+                        if (newName === '' || newName === currentName) return;
+                        $rename.prop('disabled', true);
+                        $.getJSON('KNXUltimateMatterRename?serverId=' + node.id + '&nodeId=' + encodeURIComponent(dev.nodeId) + '&name=' + encodeURIComponent(newName), function (data) {
+                            if (data && data.error) {
+                                RED.notify(data.error, { type: 'error', fixed: true });
+                            } else {
+                                RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.rename_ok") || 'Device renamed', { type: 'success' });
+                            }
+                            loadDevices();
+                        }).fail(function (jqXHR, textStatus, errorThrown) {
+                            RED.notify('Rename failed: ' + (errorThrown || textStatus), { type: 'error', fixed: true });
+                            $rename.prop('disabled', false);
+                        });
+                    });
                     var $unpair = $('<button type="button" class="red-ui-button" style="color:#c00; border-color:#c00;"><i class="fa fa-trash"></i></button>');
                     $unpair.on('click', function () {
                         var confirmMsg = RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.unpair_confirm") + ' "' + (dev.name || dev.nodeId) + '"?';
@@ -50,7 +82,7 @@
                             $unpair.prop('disabled', false);
                         });
                     });
-                    $tr.append($('<td style="text-align:right;"></td>').append($unpair));
+                    $tr.append($('<td style="text-align:right;"></td>').append($rename).append($unpair));
                     $devicesBody.append($tr);
                 });
             }
@@ -77,6 +109,7 @@
 
             $pairButton.on('click', function () {
                 var code = ($pairingCode.val() || '').trim();
+                var desiredName = ($pairingName.val() || '').trim();
                 if (code === '') {
                     RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_code_missing"), { type: 'warning' });
                     return;
@@ -89,21 +122,24 @@
                     type: 'info'
                 });
                 $.ajax({
-                    url: 'KNXUltimateMatterPair?serverId=' + node.id + '&code=' + encodeURIComponent(code),
+                    url: 'KNXUltimateMatterPair?serverId=' + node.id + '&code=' + encodeURIComponent(code) + (desiredName !== '' ? '&name=' + encodeURIComponent(desiredName) : ''),
                     dataType: 'json',
                     timeout: 180000
                 }).done(function (data) {
                     if (data && data.error) {
-                        RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_failed") + ': ' + data.error, { type: 'error', timeout: 8000 });
+                        notifyPairingError(data.error);
                     } else {
-                        RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_ok") + ' (Node ID ' + data.nodeId + ')', { type: 'success' });
+                        var pairedName = data.name || data.productName || data.nodeId;
+                        RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_ok") + ' ' + pairedName + ' (Node ID ' + data.nodeId + ')', { type: 'success' });
+                        if (data.renameError) RED.notify(data.renameError, { type: 'warning', fixed: true });
                         $pairingCode.val('');
+                        $pairingName.val('');
                         loadDevices();
                     }
                 }).fail(function (jqXHR, textStatus, errorThrown) {
                     var msg = '';
                     try { msg = jqXHR.responseJSON.error; } catch (e) { msg = errorThrown || textStatus; }
-                    RED.notify(RED._("node-red-contrib-knx-ultimate/matter-config:matter-config.properties.pairing_failed") + ': ' + msg, { type: 'error', timeout: 8000 });
+                    notifyPairingError(msg);
                 }).always(function () {
                     if (myNotification) myNotification.close();
                     $pairButton.prop('disabled', false);
@@ -193,6 +229,22 @@
     </span>
   </div>
 
+  <div class="form-row">
+    <label for="matter-pairing-name">
+      <i class="fa fa-tag"></i>
+      <span data-i18n="matter-config.properties.pairing_name"></span>
+    </label>
+    <input type="text" id="matter-pairing-name" placeholder="Kitchen plug" style="width:250px;">
+  </div>
+  <div class="form-tips" style="margin: 4px 0 8px; font-size:12px;">
+    <i class="fa fa-circle-info" style="color:#1b7d33; margin-right:4px;"></i>
+    <span data-i18n="matter-config.properties.pairing_hint">Prefer the QR code (MT:…): it carries the full device discriminator. The manual code
+    stores only a short discriminator and cannot reliably tell identical devices apart
+    (e.g. several Shelly of the same model), which can pair the wrong one or report it as
+    already commissioned. Pair one device at a time; if a device is already paired
+    elsewhere, factory-reset it first.</span>
+  </div>
+
   <hr/>
 
   <div class="form-row">
@@ -223,4 +275,4 @@
     <br/>
    <br/>
     <br/>
-</script>
+</script>

package/nodes/matter-config.js

@@ -176,15 +176,20 @@ module.exports = (RED) => {
       return node.matterManager.getNodeStructure(_nodeId)
     }
 
-    node.commission = async (_pairingCode) => {
+    node.commission = async (_pairingCode, _options = {}) => {
       if (node.matterManager === null) throw new Error('Matter controller not started')
-      return node.matterManager.commission(_pairingCode)
+      return node.matterManager.commission(_pairingCode, _options)
     }
 
     node.removeCommissionedNode = async (_nodeId) => {
       if (node.matterManager === null) throw new Error('Matter controller not started')
       return node.matterManager.removeNode(_nodeId)
     }
+
+    node.renameCommissionedNode = async (_nodeId, _label) => {
+      if (node.matterManager === null) throw new Error('Matter controller not started')
+      return node.matterManager.renameNode(_nodeId, _label)
+    }
     // END functions called from the nodes -------------------------------------------------------------
 
     node.addClient = (_Node) => {

package/nodes/matterbridge-config.html

@@ -37,6 +37,7 @@
                         info.fabrics.forEach(function (f) {
                             $pairingBody.append($('<div style="margin-left:10px;"></div>').text('• ' + (f.label || 'Controller') + ' (vendor ' + f.vendorId + ')'));
                         });
+                        $pairingBody.append($('<p style="max-width:760px; margin:14px auto 0; color:#777;"></p>').text(t('commissioned_hint')));
                         $resetButton.show();
                         return;
                     }

package/nodes/utils/lightEngines/canonicalLight.js

@@ -0,0 +1,75 @@
+'use strict'
+// Canonical, engine-agnostic light model.
+//
+// The Light node's behaviour logic (dimming ramps, day/night presets, blink,
+// colour cycle, HSV...) speaks ONLY this vocabulary. Each concrete engine
+// (Hue, Matter, future Shelly) translates a canonical patch into its native
+// shape and back. Keeping the node blind to the ecosystem is what prevents the
+// "if engine === 'hue'" spaghetti.
+//
+// A canonical patch is a plain object with any subset of:
+//   { on: boolean,
+//     brightnessPct: number 0..100,
+//     colorTempK: number (kelvin),
+//     rgb: { r, g, b } (0..255) }
+
+const clamp = (v, min, max) => Math.min(max, Math.max(min, Number(v)))
+
+const clampByte = (v, max = 254) => {
+  let n = Math.round(Number(v))
+  if (Number.isNaN(n)) n = 0
+  if (n < 0) n = 0
+  if (n > max) n = max
+  return n
+}
+
+// Kelvin <-> mired. Same physical unit; Hue calls it "mirek", Matter "mireds".
+const kelvinToMired = (kelvin) => {
+  const k = Number(kelvin)
+  if (!k || Number.isNaN(k)) return 0
+  return Math.round(1000000 / k)
+}
+const miredToKelvin = (mired) => {
+  const m = Number(mired)
+  if (!m || Number.isNaN(m)) return 0
+  return Math.round(1000000 / m)
+}
+
+// sRGB (0..255) -> CIE 1931 xy, using the Wide RGB D65 conversion Philips Hue expects.
+const rgbToXy = ({ r, g, b }) => {
+  const norm = (c) => {
+    const v = clamp(c, 0, 255) / 255
+    return v > 0.04045 ? Math.pow((v + 0.055) / 1.055, 2.4) : v / 12.92
+  }
+  const rn = norm(r)
+  const gn = norm(g)
+  const bn = norm(b)
+  const X = rn * 0.649926 + gn * 0.103455 + bn * 0.197109
+  const Y = rn * 0.234327 + gn * 0.743075 + bn * 0.022598
+  const Z = rn * 0.0000000 + gn * 0.053077 + bn * 1.035763
+  const sum = X + Y + Z
+  if (sum === 0) return [0, 0]
+  return [Number((X / sum).toFixed(4)), Number((Y / sum).toFixed(4))]
+}
+
+// RGB (0..255) -> HSV. hue in 0..360, sat/val in 0..1.
+const rgbToHsv = ({ r, g, b }) => {
+  const rn = clamp(r, 0, 255) / 255
+  const gn = clamp(g, 0, 255) / 255
+  const bn = clamp(b, 0, 255) / 255
+  const max = Math.max(rn, gn, bn)
+  const min = Math.min(rn, gn, bn)
+  const d = max - min
+  let h = 0
+  if (d !== 0) {
+    if (max === rn) h = ((gn - bn) / d) % 6
+    else if (max === gn) h = (bn - rn) / d + 2
+    else h = (rn - gn) / d + 4
+    h *= 60
+    if (h < 0) h += 360
+  }
+  const s = max === 0 ? 0 : d / max
+  return { h, s, v: max }
+}
+
+module.exports = { clamp, clampByte, kelvinToMired, miredToKelvin, rgbToXy, rgbToHsv }

package/nodes/utils/lightEngines/hueLightEngine.js

@@ -0,0 +1,51 @@
+'use strict'
+const { LightEngine } = require('./lightEngine')
+const { clampByte, kelvinToMired, miredToKelvin, rgbToXy } = require('./canonicalLight')
+
+// Hue speaks a single COMPOSITE, atomic state object (Hue API v2 shape):
+//   { on:{on}, dimming:{brightness}, color:{xy}, color_temperature:{mirek} }
+// so a canonical patch collapses into ONE writeHueQueueAdd call.
+class HueLightEngine extends LightEngine {
+  constructor (opts = {}) {
+    super(opts)
+    this.manager = opts.manager // hue-config's hueManager (writeHueQueueAdd)
+    this.operation = opts.grouped ? 'setGroupedLight' : 'setLight'
+  }
+
+  get kind () { return 'hue' }
+
+  capabilities () {
+    return { onOff: true, dimming: true, colorTemp: true, color: true, effects: true }
+  }
+
+  translate (patch) {
+    const state = {}
+    if (patch.on !== undefined) state.on = { on: !!patch.on }
+    if (patch.brightnessPct !== undefined) state.dimming = { brightness: clampByte(patch.brightnessPct, 100) }
+    if (patch.colorTempK !== undefined) state.color_temperature = { mirek: kelvinToMired(patch.colorTempK) }
+    if (patch.rgb !== undefined) state.color = { xy: { x: rgbToXy(patch.rgb)[0], y: rgbToXy(patch.rgb)[1] } }
+    return state
+  }
+
+  applyState (patch) {
+    const state = this.translate(patch)
+    if (Object.keys(state).length === 0) return []
+    if (this.manager && typeof this.manager.writeHueQueueAdd === 'function') {
+      this.manager.writeHueQueueAdd(this.deviceId, state, this.operation)
+    }
+    return [{ api: 'writeHueQueueAdd', deviceId: this.deviceId, state, operation: this.operation }]
+  }
+
+  // Hue resource object (as delivered to handleSendHUE) -> canonical patch.
+  parseIncoming (event) {
+    if (!event) return null
+    if (event.id !== undefined && event.id !== this.deviceId) return null
+    const patch = {}
+    if (event.on && event.on.on !== undefined) patch.on = !!event.on.on
+    if (event.dimming && event.dimming.brightness !== undefined) patch.brightnessPct = Number(event.dimming.brightness)
+    if (event.color_temperature && event.color_temperature.mirek) patch.colorTempK = miredToKelvin(event.color_temperature.mirek)
+    return Object.keys(patch).length ? patch : null
+  }
+}
+
+module.exports = { HueLightEngine }

package/nodes/utils/lightEngines/index.js

@@ -0,0 +1,25 @@
+'use strict'
+// Factory + registry for light engines. Adding a new ecosystem (e.g. Shelly)
+// is a one-line registration here + one new *LightEngine file: the Light node
+// and its behaviour logic stay untouched.
+const { LightEngine } = require('./lightEngine')
+const { HueLightEngine } = require('./hueLightEngine')
+const { MatterLightEngine } = require('./matterLightEngine')
+
+const ENGINES = {
+  hue: HueLightEngine,
+  matter: MatterLightEngine
+  // shelly: ShellyLightEngine  <-- future: just add the class + this line
+}
+
+function createLightEngine (kind, opts = {}) {
+  const Engine = ENGINES[kind]
+  if (!Engine) {
+    throw new Error(`Unknown light engine "${kind}". Available: ${Object.keys(ENGINES).join(', ')}`)
+  }
+  return new Engine(opts)
+}
+
+const availableEngines = () => Object.keys(ENGINES)
+
+module.exports = { createLightEngine, availableEngines, LightEngine, HueLightEngine, MatterLightEngine }

package/nodes/utils/lightEngines/knxLightCommand.js

@@ -0,0 +1,79 @@
+'use strict'
+const { miredToKelvin } = require('./canonicalLight')
+
+// Linear scale, mirrors hueColorConverter.ColorConverter.scale.
+const scale = (v, [inMin, inMax], [outMin, outMax]) =>
+  outMin + ((Number(v) - inMin) * (outMax - outMin)) / (inMax - inMin)
+
+const truthy = (v) => v === true || v === 1 || v === '1' || v === 'true' || v === 'on'
+
+// Pure, engine-agnostic mapping of a DECODED KNX light group-address value into a
+// canonical patch. `value` is the already dpt-decoded payload, so this stays free
+// of knxultimate/dptlib and is trivially unit-testable.
+//
+// Returns:
+//   { patch }              -> a canonical patch to push to the engine
+//   { unsupported: reason } -> a Hue-only behaviour with no Matter equivalent
+//   null                   -> destination not handled by the light command path
+function canonicalizeKnxLightCommand ({ config, destination, value, dayTime = true }) {
+  switch (destination) {
+    case config.GALightSwitch: {
+      const on = truthy(value)
+      const patch = { on }
+      // Parity with the Hue switch-on preset (temperature mode): a Matter light
+      // turns on with the same day/night brightness + colour temperature.
+      if (on && config.specifySwitchOnBrightness === 'temperature') {
+        const preset = (dayTime === false && config.enableDayNightLighting === 'temperature')
+          ? config.colorAtSwitchOnNightTime
+          : config.colorAtSwitchOnDayTime
+        if (preset && typeof preset === 'object') {
+          if (preset.brightness !== undefined) patch.brightnessPct = Number(preset.brightness)
+          if (preset.kelvin !== undefined) patch.colorTempK = Number(preset.kelvin)
+        }
+      }
+      return { patch }
+    }
+    case config.GALightBrightness: {
+      const pct = Number(value)
+      if (Number.isNaN(pct)) throw new Error('Invalid KNX brightness payload')
+      return { patch: { brightnessPct: pct, on: pct > 0 } }
+    }
+    case config.GALightKelvin: {
+      const kelvin = Math.min(6535, Math.max(2000, Number(value)))
+      return { patch: { colorTempK: kelvin } }
+    }
+    case config.GALightKelvinPercentage: {
+      if (config.dptLightKelvinPercentage !== '5.001') return null
+      const mirek = scale(100 - Number(value), [0, 100], [153, 500])
+      return { patch: { colorTempK: miredToKelvin(mirek) } }
+    }
+    case config.GALightColor: {
+      if (!value || typeof value !== 'object') return null
+      return { patch: { rgb: { r: value.red, g: value.green, b: value.blue } } }
+    }
+    case config.GALightDIM:
+    case config.GALightHSV_H_DIM:
+    case config.GALightHSV_S_DIM:
+    case config.GALightKelvinDIM:
+      return { unsupported: 'Relative/HSV dimming not supported on Matter' }
+    case config.GALightBlink:
+    case config.GALightColorCycle:
+      return { unsupported: 'Effect not supported on Matter' }
+    default:
+      return null
+  }
+}
+
+// The DPT that must be used to decode a given destination GA.
+function dptForDestination (config, destination) {
+  switch (destination) {
+    case config.GALightSwitch: return config.dptLightSwitch
+    case config.GALightBrightness: return config.dptLightBrightness
+    case config.GALightKelvin: return config.dptLightKelvin
+    case config.GALightKelvinPercentage: return config.dptLightKelvinPercentage
+    case config.GALightColor: return config.dptLightColor
+    default: return null
+  }
+}
+
+module.exports = { canonicalizeKnxLightCommand, dptForDestination }

package/nodes/utils/lightEngines/lightEngine.js

@@ -0,0 +1,46 @@
+'use strict'
+// Abstract LightEngine: the single seam between the Light node's engine-agnostic
+// behaviour logic and a concrete ecosystem (Hue, Matter, ...future Shelly).
+//
+// A concrete engine must implement:
+//   - applyState(patch): push a canonical patch toward the ecosystem
+//   - parseIncoming(event): turn a native ecosystem event into a canonical patch
+//   - capabilities(): advertise what it can honour, so the node can degrade
+//     gracefully (e.g. native Hue effects have no Matter equivalent)
+
+class LightEngine {
+  constructor (opts = {}) {
+    this.deviceId = opts.deviceId
+    this._onState = typeof opts.onStateChange === 'function' ? opts.onStateChange : () => {}
+  }
+
+  get kind () { return 'abstract' }
+
+  capabilities () {
+    return { onOff: false, dimming: false, colorTemp: false, color: false, effects: false }
+  }
+
+  // Canonical patch -> native ecosystem call(s). Returns the list of native
+  // operations issued (useful for tests and status/debug).
+  applyState (_patch) {
+    throw new Error(`${this.kind}: applyState not implemented`)
+  }
+
+  // Native ecosystem event -> canonical patch, or null when irrelevant.
+  parseIncoming (_event) {
+    return null
+  }
+
+  // Feed a native event and, when relevant, emit the canonical patch upward
+  // (to the node, which writes it to KNX). Keeps parseIncoming pure/testable.
+  handleIncoming (event) {
+    let patch = null
+    try {
+      patch = this.parseIncoming(event)
+      if (patch && Object.keys(patch).length > 0) this._onState(patch)
+    } catch (error) { /* a bad event / feedback sink must never crash the caller */ }
+    return patch
+  }
+}
+
+module.exports = { LightEngine }

package/nodes/utils/lightEngines/matterHueShim.js

@@ -0,0 +1,59 @@
+'use strict'
+// Boundary shim that lets the (copied) Hue Light logic drive a MATTER light untouched.
+// The node keeps speaking Hue-native composite states ({on:{on}}, {dimming:{brightness}},
+// {color:{xy}}, {color_temperature:{mirek}}); these pure functions translate them to the
+// canonical light model (for MatterLightEngine) and Matter attribute reports back into
+// Hue-shaped feedback patches.
+const hueColorConverter = require('../colorManipulators/hueColorConverter')
+const { matterToKnx } = require('../matterKnxConverter')
+
+// Hue-native state object -> canonical patch { on, brightnessPct, colorTempK, rgb }.
+function hueStateToCanonical (hueState) {
+  try {
+    return _hueStateToCanonical(hueState)
+  } catch (error) {
+    return null
+  }
+}
+function _hueStateToCanonical (hueState) {
+  if (!hueState || typeof hueState !== 'object') return null
+  const patch = {}
+  if (hueState.on && hueState.on.on !== undefined) patch.on = !!hueState.on.on
+  if (hueState.dimming && hueState.dimming.brightness !== undefined) patch.brightnessPct = Number(hueState.dimming.brightness)
+  if (hueState.color_temperature && hueState.color_temperature.mirek) patch.colorTempK = Math.round(1000000 / Number(hueState.color_temperature.mirek))
+  if (hueState.color && hueState.color.xy && hueState.color.xy.x !== undefined) {
+    const bri = patch.brightnessPct !== undefined ? patch.brightnessPct : 100
+    try {
+      const rgb = hueColorConverter.ColorConverter.xyBriToRgb(Number(hueState.color.xy.x), Number(hueState.color.xy.y), bri)
+      patch.rgb = { r: rgb.r, g: rgb.g, b: rgb.b }
+    } catch (error) { /* colour conversion failed: skip the colour part */ }
+  }
+  return Object.keys(patch).length ? patch : null
+}
+
+// Matter attribute report -> feedback patch for the node
+// { on } | { brightnessPct } | { colorTempK, mirek } | { xyX } | { xyY } | null.
+function matterEventToHuePatch (event) {
+  try {
+    if (!event || event.attributeName === undefined) return null
+    switch (event.attributeName) {
+      case 'onOff':
+        return { on: event.value === true }
+      case 'currentLevel': {
+        const v = matterToKnx(Number(event.clusterId), 'currentLevel', event.value)
+        return v === undefined ? null : { brightnessPct: Number(v) }
+      }
+      case 'colorTemperatureMireds': {
+        const m = Number(event.value)
+        return m > 0 ? { colorTempK: Math.round(1000000 / m), mirek: m } : null
+      }
+      case 'currentX': return { xyX: Number(event.value) / 65536 }
+      case 'currentY': return { xyY: Number(event.value) / 65536 }
+      default: return null
+    }
+  } catch (error) {
+    return null
+  }
+}
+
+module.exports = { hueStateToCanonical, matterEventToHuePatch }