node-red-contrib-knx-ultimate 6.2.2 → 6.2.3-beta.0

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

@@ -0,0 +1,48 @@
+{
+  "common": {
+    "knx_gw": "KNX 网关",
+    "hue_bridge": "Hue Bridge"
+  },
+  "knxUltimateHueController": {
+    "device_function": "设备功能",
+    "legacy_node_notice": "此旧版 HUE 节点已弃用。新流程请使用新的 HUE Controller 节点。",
+    "migration_button": "转换旧版 HUE 流程",
+    "migration_button_title": "粘贴 Node-RED 流程并转换其中的旧版 HUE 节点",
+    "migration_title": "转换旧版 HUE 流程",
+    "migration_privacy": "粘贴从 Node-RED 导出的流程。转换仅在本地进行，不会修改当前打开的流程。",
+    "migration_credentials_notice": "Node-RED 会特意从导出的流程中排除密钥和密码。转换器无法读取或重新创建这些凭据。",
+    "migration_reuse_configs": "复用现有 Hue 和 KNX 配置节点（推荐）",
+    "migration_reuse_configs_help": "重新导入同一个 Node-RED 实例时请保持选中。结果会省略被引用的配置节点，从而保留其中已存储的凭据。",
+    "migration_input": "原始流程 JSON",
+    "migration_input_placeholder": "在此粘贴完整的 Node-RED 流程导出内容",
+    "migration_convert": "转换",
+    "migration_copy": "复制转换后的流程",
+    "migration_output": "转换后的流程 JSON",
+    "migration_close": "关闭",
+    "migration_summary": "已转换 {{count}} 个旧版 HUE 节点。",
+    "migration_summary_reused": "将复用 {{count}} 个被引用的配置节点及其现有凭据。",
+    "migration_configs_included_warning": "配置节点已包含在结果中，但不含导出的凭据；请在导入后重新输入密钥和密码。",
+    "migration_none": "未找到旧版 HUE 节点。",
+    "migration_invalid": "流程 JSON 无效：",
+    "migration_copy_success": "已复制转换后的流程。",
+    "migration_copy_failed": "剪贴板访问被阻止。已选中转换后的 JSON，请手动复制。",
+    "migration_unavailable": "HUE 迁移工具不可用。更新软件包后请重启 Node-RED。",
+    "types": {
+      "light": "灯 / 灯组",
+      "plug": "插座 / 输出",
+      "button": "按钮",
+      "relative_rotary": "Tap dial",
+      "motion": "运动",
+      "area_motion": "区域运动",
+      "camera_motion": "摄像机运动",
+      "contact": "接触传感器",
+      "light_level": "光照度",
+      "temperature": "温度",
+      "humidity": "湿度",
+      "scene": "场景",
+      "device_power": "电池",
+      "zigbee_connectivity": "Zigbee 连接",
+      "device_software_update": "设备软件更新"
+    }
+  }
+}

package/nodes/locales/zh-CN/knxUltimateHueHumiditySensor.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueHumiditySensor">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>该节点从 HUE 湿度传感器读取相对湿度 (%) 并映射到 KNX。</p>
 
 在 GA 字段中开始输入（名称或组地址）以关联 KNX GA；输入时会显示匹配的设备。

package/nodes/locales/zh-CN/knxUltimateHueLight.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueLight">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>此节点使您可以控制飞利浦色调灯和分组的灯光，还可以将此灯的状态发送到KNX巴士。</p>
 
 **一般的**

package/nodes/locales/zh-CN/knxUltimateHueLightSensor.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueLightSensor">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>该节点从 HUE 光照传感器读取 Lux 事件并发布到 KNX。</p>
 
 每当环境光变化时会输出 Lux 值。在 GA 字段输入 KNX 设备名或组地址（自动补全）以进行关联。

package/nodes/locales/zh-CN/knxUltimateHueMotion.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueMotion">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>该节点订阅 Hue 运动传感器的事件，并将其同步到 KNX 以及 Node-RED 流程。</p>
 
 在 GA 字段输入 KNX 设备名称或组地址即可自动补全；"Hue 传感器”旁的刷新按钮可重新加载 Hue 设备列表。

package/nodes/locales/zh-CN/knxUltimateHuePlug.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHuePlug">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 # Hue 插座 / Plug
 
 ## 概述

package/nodes/locales/zh-CN/knxUltimateHueScene.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueScene">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 **Hue Scene** 节点将 Hue 场景发布到 KNX，并且可以把 Hue 的原始事件发送到 Node-RED 流程。场景字段支持自动补全；在网桥中新增场景后，请点击刷新图标更新列表。
 
 ### 选项卡概览

package/nodes/locales/zh-CN/knxUltimateHueTapDial.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueTapDial">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 **Hue Tap Dial** 节点将 Tap Dial 的旋转服务映射到 KNX，并把原始 Hue 事件发送到 Node-RED 流程。配对新设备后，请点击设备字段旁的刷新图标。
 
 ### 选项卡

package/nodes/locales/zh-CN/knxUltimateHueTemperatureSensor.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueTemperatureSensor">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>此节点读取 HUE 温度传感器的温度（°C），并将其映射到 KNX。</p>
 
 在 GA 字段（名称或组地址）中输入以关联 KNX GA；输入时会显示设备建议。

package/nodes/locales/zh-CN/knxUltimateHueZigbeeConnectivity.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHueZigbeeConnectivity">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>该节点从 HUE 设备读取 Zigbee 连接状态，并发布到 KNX。</p>
 
 在 GA 字段输入 KNX 设备名或组地址，输入时会自动联想。

package/nodes/locales/zh-CN/knxUltimateHuedevice_software_update.html

@@ -1,4 +1,5 @@
 <script type="text/markdown" data-help-name="knxUltimateHuedevice_software_update">
+<p><strong>已弃用：</strong>此专用 HUE 节点仍可用于现有流程。新项目请使用 <strong>HUE Controller</strong>。旧版节点会在节点面板和画布上标记为 <code>(deprecated)</code>，颜色比 HUE Controller 更浅，编辑器顶部也会显示迁移提示。 此编辑器中的橙色迁移按钮会打开与 HUE Controller 相同的完整流程转换器。</p>
 <p>该节点监控 HUE 设备的软件更新状态，并发布到 KNX。</p>
 
 开始在GA字段中键入KNX设备的名称或组地址，可用的设备开始显示

package/nodes/utils/hueControllerProfileAdapter.js

@@ -0,0 +1,104 @@
+'use strict'
+
+// These are the canonical runtime implementations owned by HUE Controller.
+// They deliberately keep the familiar "module receives RED, then calls
+// registerType" shape: that lets us preserve the well-tested lifecycle of each
+// dedicated Hue implementation without registering fifteen more public nodes.
+//
+// None of these paths is listed under `node-red.nodes` in package.json. Node-RED
+// therefore never loads them as palette nodes, and deleting a legacy entry point
+// cannot remove code required by HUE Controller.
+const RUNTIME_MODULES = Object.freeze({
+  light: './hueControllerProfiles/runtime/light',
+  plug: './hueControllerProfiles/runtime/plug',
+  button: './hueControllerProfiles/runtime/button',
+  relative_rotary: './hueControllerProfiles/runtime/relative_rotary',
+  motion: './hueControllerProfiles/runtime/motion',
+  area_motion: './hueControllerProfiles/runtime/area_motion',
+  camera_motion: './hueControllerProfiles/runtime/camera_motion',
+  contact: './hueControllerProfiles/runtime/contact',
+  light_level: './hueControllerProfiles/runtime/light_level',
+  temperature: './hueControllerProfiles/runtime/temperature',
+  humidity: './hueControllerProfiles/runtime/humidity',
+  scene: './hueControllerProfiles/runtime/scene',
+  device_power: './hueControllerProfiles/runtime/device_power',
+  zigbee_connectivity: './hueControllerProfiles/runtime/zigbee_connectivity',
+  device_software_update: './hueControllerProfiles/runtime/device_software_update'
+})
+
+// A constructor closes over the RED instance used while loading its module.
+// Cache by RED first (rather than globally) so tests, embedded runtimes and future
+// hot-reload scenarios never accidentally share constructors across runtimes.
+// WeakMap also means an abandoned RED instance is not kept alive by this adapter.
+const constructors = new WeakMap()
+
+const getConstructorCache = (RED) => {
+  let cache = constructors.get(RED)
+  if (!cache) {
+    cache = new Map()
+    constructors.set(RED, cache)
+  }
+  return cache
+}
+
+const captureRuntimeConstructor = (RED, controllerType) => {
+  const modulePath = RUNTIME_MODULES[controllerType]
+  if (!modulePath) return undefined
+
+  const cache = getConstructorCache(RED)
+  if (cache.has(controllerType)) return cache.get(controllerType)
+
+  let capturedConstructor
+
+  // The private modules believe they are registering an ordinary node. The
+  // facade delegates every real RED service through the prototype chain but
+  // intercepts only registerType, turning registration into constructor capture.
+  // The real Node-RED registry is never touched here.
+  const redFacade = Object.create(RED)
+  redFacade.nodes = Object.create(RED.nodes)
+  redFacade.nodes.registerType = (_type, constructor) => {
+    capturedConstructor = constructor
+  }
+
+  // CommonJS itself caches the module source; our per-RED cache stores the
+  // constructor produced by invoking its exported registration function.
+  require(modulePath)(redFacade)
+  if (typeof capturedConstructor !== 'function') {
+    throw new Error(`Unable to load HUE Controller runtime for ${controllerType}`)
+  }
+
+  cache.set(controllerType, capturedConstructor)
+  return capturedConstructor
+}
+
+const normalizeControllerType = (config = {}) => {
+  // `hueControllerType` is the authoritative new field. The resource suffix is
+  // a compatibility safety net for imported or partially migrated flows.
+  const configuredType = String(config.hueControllerType || '').trim()
+  if (RUNTIME_MODULES[configuredType]) return configuredType
+
+  const resourceType = String(config.hueDevice || '').split('#')[1] || ''
+  if (RUNTIME_MODULES[resourceType]) return resourceType
+
+  // grouped_light intentionally falls through to light: both resource kinds
+  // use the same mature light runtime and there is no separate grouped profile.
+  return 'light'
+}
+
+const setupHueControllerRuntime = (RED, node, config) => {
+  const controllerType = normalizeControllerType(config)
+  const RuntimeConstructor = captureRuntimeConstructor(RED, controllerType)
+
+  // Execute the selected constructor *on the Controller instance*. Its own
+  // RED.nodes.createNode call installs all normal Node-RED lifecycle hooks,
+  // while the persisted public type remains knxUltimateHueController.
+  RuntimeConstructor.call(node, config)
+  node.hueControllerType = controllerType
+}
+
+module.exports = {
+  RUNTIME_MODULES,
+  captureRuntimeConstructor,
+  normalizeControllerType,
+  setupHueControllerRuntime
+}

package/nodes/utils/hueControllerProfiles/runtime/area_motion.js

@@ -0,0 +1,221 @@
+// Canonical private runtime profile for HUE Controller: area_motion.
+// This module is shipped with the Controller but is intentionally absent from
+// package.json, so Node-RED never registers it as a separate palette node.
+module.exports = function (RED) {
+  function knxUltimateHueAreaMotion (config) {
+    RED.nodes.createNode(this, config)
+    const node = this
+    node.serverKNX = RED.nodes.getNode(config.server) || undefined
+    node.serverHue = RED.nodes.getNode(config.serverHue) || undefined
+    node.topic = node.name
+    node.name = config.name === undefined ? 'Hue' : config.name
+    node.dpt = ''
+    node.notifyreadrequest = true
+    node.notifyreadrequestalsorespondtobus = 'false'
+    node.notifyreadrequestalsorespondtobusdefaultvalueifnotinitialized = ''
+    node.notifyresponse = false
+    node.notifywrite = true
+    node.initialread = true
+    node.listenallga = true
+    node.outputtype = 'write'
+    node.outputRBE = 'false'
+    node.inputRBE = 'false'
+    node.currentPayload = ''
+    node.passthrough = 'no'
+    node.formatmultiplyvalue = 1
+    node.formatnegativevalue = 'leave'
+    node.formatdecimalsvalue = 2
+    node.hueDevice = config.hueDevice
+    node.dptAreaMotion = config.dptAreaMotion
+    node.motionDPT = (config.dptAreaMotion && config.dptAreaMotion !== '') ? config.dptAreaMotion : '1.001'
+    node.initializingAtStart = (config.readStatusAtStartup === undefined || config.readStatusAtStartup === 'yes')
+    node.currentDeviceValue = false
+    node.enableNodePINS = (config.enableNodePINS === undefined || config.enableNodePINS === 'yes')
+    node.outputs = node.enableNodePINS ? 1 : 0
+
+    if (!node.serverKNX && node.enableNodePINS !== 'yes') {
+      node.enableNodePINS = 'yes'
+      node.outputs = 1
+    }
+
+    const pushStatus = (status) => {
+      if (!status) return
+      const provider = node.serverKNX
+      if (provider && typeof provider.applyStatusUpdate === 'function') {
+        provider.applyStatusUpdate(node, status)
+      } else {
+        node.status(status)
+      }
+    }
+
+    const updateStatus = (status) => {
+      if (!status) return
+      pushStatus(status)
+    }
+
+    const formatTs = (date) => {
+      const d = date instanceof Date ? date : new Date(date)
+      const provider = node.serverKNX
+      if (provider && typeof provider.formatStatusTimestamp === 'function') return provider.formatStatusTimestamp(d)
+      return `${d.getDate()}, ${d.toLocaleTimeString()}`
+    }
+
+    const safeSendToKNX = (telegram, context = 'write') => {
+      try {
+        if (!node.serverKNX || typeof node.serverKNX.sendKNXTelegramToKNXEngine !== 'function') {
+          const now = new Date()
+          updateStatus({ fill: 'red', shape: 'dot', text: `KNX server missing (${context}) (${formatTs(now)})` })
+          return
+        }
+        node.serverKNX.sendKNXTelegramToKNXEngine({ ...telegram, nodecallerid: node.id })
+      } catch (error) {
+        updateStatus({ fill: 'red', shape: 'dot', text: `KNX send error ${error.message}` })
+      }
+    }
+
+    node.setNodeStatus = ({ fill, shape, text, payload }) => {
+      try {
+        if (payload === undefined) payload = ''
+        const dDate = new Date()
+        payload = typeof payload === 'object' ? JSON.stringify(payload) : payload.toString()
+        node.sKNXNodeStatusText = `|KNX: ${text} ${payload} (${formatTs(dDate)})`
+        pushStatus({ fill, shape, text: (node.sHUENodeStatusText || '') + ' ' + (node.sKNXNodeStatusText || '') })
+      } catch (error) { }
+    }
+
+    node.setNodeStatusHue = ({ fill, shape, text, payload }) => {
+      try {
+        if (payload === undefined) payload = ''
+        const dDate = new Date()
+        payload = typeof payload === 'object' ? JSON.stringify(payload) : payload.toString()
+        node.sHUENodeStatusText = `|HUE: ${text} ${payload} (${formatTs(dDate)})`
+        pushStatus({ fill, shape, text: node.sHUENodeStatusText + ' ' + (node.sKNXNodeStatusText || '') })
+      } catch (error) { }
+    }
+
+    const mapMotionValue = (_event) => {
+      const motion = _event?.motion
+      if (!motion) return undefined
+
+      const readBoolean = (candidate) => {
+        if (typeof candidate === 'boolean') return candidate
+        if (candidate && typeof candidate.value === 'boolean') return candidate.value
+        return undefined
+      }
+
+      let value = readBoolean(motion.motion)
+      if (value === undefined && motion.motion_report) {
+        value = readBoolean(motion.motion_report.motion)
+      }
+      if (value === undefined && motion.motion_report && typeof motion.motion_report.motion === 'boolean') {
+        value = motion.motion_report.motion
+      }
+      if (value === undefined && typeof motion.motion_valid === 'boolean') {
+        value = motion.motion_valid
+      }
+      if (value === undefined) {
+        value = readBoolean(motion.motion_valid)
+      }
+      return value
+    }
+
+    node.handleSend = (msg) => {
+      if (!msg || !msg.knx) return
+      if (msg.knx.event === 'GroupValue_Read') {
+        switch (msg.knx.destination) {
+          case config.GAareaMotion:
+            node.sendResponseToKNX(node.currentDeviceValue)
+            break
+          default:
+            break
+        }
+      }
+    }
+
+    node.handleSendHUE = (_event) => {
+      try {
+        if (_event.id !== config.hueDevice) return
+        const motionValue = mapMotionValue(_event)
+        if (motionValue === undefined) return
+
+        const knxMsgPayload = {
+          topic: config.GAareaMotion,
+          dpt: node.motionDPT,
+          payload: motionValue === true || motionValue === 1 || motionValue === '1' ? true : Boolean(motionValue),
+          name: node.name,
+          event: 'motion',
+          rawEvent: _event
+        }
+
+        if (knxMsgPayload.topic) {
+          safeSendToKNX({
+            grpaddr: knxMsgPayload.topic,
+            payload: knxMsgPayload.payload,
+            dpt: knxMsgPayload.dpt,
+            outputtype: 'write'
+          }, 'write')
+        }
+        node.currentDeviceValue = knxMsgPayload.payload
+
+        updateStatus({
+          fill: 'green',
+          shape: 'dot',
+          text: `HUE->KNX ${knxMsgPayload.payload} (${formatTs(new Date())})`
+        })
+
+        if (node.enableNodePINS) {
+          node.send(knxMsgPayload)
+        }
+        node.setNodeStatusHue({
+          fill: 'blue',
+          shape: 'ring',
+          text: 'HUE->KNX',
+          payload: knxMsgPayload.payload
+        })
+      } catch (error) {
+        updateStatus({
+          fill: 'red',
+          shape: 'dot',
+          text: `HUE->KNX error ${error.message} (${formatTs(new Date())})`
+        })
+      }
+    }
+
+    node.sendResponseToKNX = (_level) => {
+      if (!node.serverKNX) return
+      const knxMsgPayload = {
+        topic: config.GAareaMotion,
+        dpt: node.motionDPT,
+        payload: !!(_level === true || _level === 1 || _level === '1')
+      }
+      if (knxMsgPayload.topic) {
+        safeSendToKNX({
+          grpaddr: knxMsgPayload.topic,
+          payload: knxMsgPayload.payload,
+          dpt: knxMsgPayload.dpt,
+          outputtype: 'response'
+        }, 'response')
+      }
+    }
+
+    if (node.serverKNX) {
+      node.serverKNX.removeClient(node)
+      node.serverKNX.addClient(node)
+    }
+    if (node.serverHue) {
+      node.serverHue.removeClient(node)
+      node.serverHue.addClient(node)
+    }
+
+    node.on('close', (done) => {
+      if (node.serverKNX) {
+        node.serverKNX.removeClient(node)
+      }
+      if (node.serverHue) {
+        node.serverHue.removeClient(node)
+      }
+      done()
+    })
+  }
+  RED.nodes.registerType('knxUltimateHueAreaMotion', knxUltimateHueAreaMotion)
+}