HUE Controller

KNX-Ultimate 视频教程（YouTube 播放列表）

一个节点提供全部功能

一致的 Controller 使用体验

• 提供统一的 Hue 设备/资源自动完成和刷新，并自动确定对应功能。
• 单击设备字段或使其获得焦点时，即使已有选择，也会打开完整的 Hue 列表；输入文字可筛选列表。
• 灯具映射会根据能力显示：调光、可调白光、RGB/HSV 和原生效果遵循所选 Hue API v2 灯资源实时提供的 dimming、color_temperature、color 和 effects 属性。
• 灯光编辑器使用有界就绪等待：Hue Bridge 加载资源时显示旋转沙漏，每 500 毫秒检查一次，并在约 10 秒后解除等待并显示本地化错误。保存、关闭或切换功能都会取消计时器。
• 紧凑的 KNX 映射行会将 GA、DPT 和名称保持在同一行；DPT 与名称控件采用较小宽度，在较窄的编辑器中名称字段还可继续收缩，且不会改变已保存的值。选择器选项异步加载时，已保存的 DPT 值会被保留。
• KNX 网关可选：可使用组地址或导入的 ETS 名称；兼容的数据点来自所选网关。
• 按配置动态提供 Node-RED 端口，用于经过验证的 Hue API v2 输入及受支持的 Hue 事件输出。
• 每个私有配置都保留启动读取、Hue→KNX 状态同步和回路保护。
• 可完全在本地迁移全部十五种旧版节点类型；随后打开可编辑的邮件草稿，在最终消息中提供可选支持按钮，并在本地检查后手动 Deploy。

四步开始使用

1. 只需配置一次 Hue Bridge。
2. 添加 HUE Controller，选择或刷新 Hue 设备；设备类型会自动填写。
3. 选择 KNX 网关并映射命令/状态，或保留 none 仅用于流程。
4. 设置该功能的行为和端口，部署并检查节点实时状态。

没有 KNX 网关？ Controller 仍可作为 Hue–Node-RED 集成使用。KNX 字段会隐藏，所选功能支持的流程选项仍然可用。

下面各节是从原有专用节点整合而来的完整功能参考。

转换旧版 HUE 节点

仅当 Node-RED 编辑器在当前流程中检测到至少一个旧版 HUE 节点时，迁移按钮才会显示。HUE Controller 和每个旧版 HUE 编辑器中，带白色文字的高对比度橙色按钮前都会显示一个迁移说明视频的 YouTube 链接。按钮下方的声明确认不会有任何流程或节点数据离开浏览器。

点击转换旧版 HUE 节点并确认。浏览器会在本地完成全部转换，不会发送任何流程、节点、hue-config、knxUltimate-config、组地址、连线、凭据、名称、位置或 ID 数据。转换成功后，它只会打开一封发给作者的可编辑邮件草稿，而不会离开 Node-RED。草稿只包含已转换节点数量和可选备注空间；是否发送由你决定，绝不会自动发送。最终的 Node-RED 消息会提供一个可选支持按钮；只有点击该按钮时才会打开捐赠页面。

开始之前，请先导出流程备份。浏览器会关闭当前节点编辑器，并只把检测到的旧版 HUE 节点转换为 HUE Controller 实例。已保存的属性、配置引用、位置、分组和连线保持不变。工作区会标记为已修改，但工具绝不会自动部署：请检查结果并自行点击 Deploy。节点已变化、流程被锁定或发生本地转换错误时，工作区不会发生变化。安全检查：点击 Deploy 前，请逐一检查所有已修改 HUE 节点的功能、配置引用、输入/输出端口和连线。处理完成后，Node-RED 的固定消息会一直显示，直到点击确定。

Hue 事件仍然只是状态更新，不会变成新的 Hue 命令。HUE Controller 内置私有的运行时、编辑器、模板和翻译配置，因此不依赖加载已弃用的节点类型。原始 Hue Light 节点保持不变。原有专用 Hue 节点仍会注册以兼容现有流程，但这些节点现已冻结，不再获得新功能或维护更新。Node-RED 会从节点面板中隐藏其特殊的 deprecated 分类；现有实例仍可编辑和部署，颜色比 HUE Controller 更浅，会在画布上标记为 (deprecated)，编辑器顶部也会显示迁移提示。

设备功能

• 灯 / 灯组 (light)
• 插座 / 输出 (plug)
• 按钮 (button)
• Tap dial (relative_rotary)
• 运动 (motion)
• 区域运动 (area_motion)
• 摄像机运动 (camera_motion)
• 接触传感器 (contact)
• 光照度 (light_level)
• 温度 (temperature)
• 湿度 (humidity)
• 场景 (scene)
• 电池 (device_power)
• Zigbee 连接 (zigbee_connectivity)
• 设备软件更新 (device_software_update)

灯 / 灯组 (light)

此节点使您可以控制飞利浦色调灯和分组的灯光，还可以将此灯的状态发送到KNX巴士。

一般的

定位设备

Locate 按钮（播放图标）会为所选资源启动 Hue Identify 会话。会话激活期间，按钮会切换为停止图标，网桥每秒让该灯具——或分组中的所有灯具——闪烁一次。再次按下按钮可立即停止；否则会在 10 分钟后自动结束。

选项

在这里，您可以选择要链接到可用的色调灯/状态的KNX地址。

开始输入GA字段，KNX设备的名称或组地址，可用设备在输入时开始显示。

转变

暗淡

可调白

** RGB/HSV **

提示：HSV 的 “V”（亮度）请使用 Dim 选项卡的标准控件。

效果

非 Hue 基础效果

Hue 原生效果

在 Hue 原生效果 表格中，把 KNX 值映射到灯具支持的效果（例如 candle、fireplace、prism）。每一行把一个 KNX 值（布尔、数值或文本，取决于所选数据点）与桥接器返回的某个效果关联。这样可以：

• 发送映射好的 KNX 值来触发对应的效果；
• （可选）配置一个状态组地址：当 Hue 桥上报效果变化时，节点会回写映射值；如果未找到映射，则发送原始效果名称（需要文本类 DPT，例如 16.xxx）。

行为

|属性|描述| |—————————————————– |—————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————-| |在启动时阅读状态|在Node-Red的启动或Node-Red的完整部署中阅读色相灯状态，然后将该状态发送到KNX总线| |KNX亮度状态|每当打开/关闭色调灯时，都会更新KNX亮度组地址状态。选项是 当色相关闭时发送0％。当色相打开时，还原以前的值（默认的KNX行为） ** 和如IS（默认色调行为）** 。如果您具有具有亮度状态的KNX调光器，例如MDT，则建议的选项为***，当Hue Light关闭时，请发送0％。色调打开时，还原以前的值（默认的KNX行为）*** | |根据 KNX 总线写入更新本地缓存的 Hue 状态|高级选项，默认启用。启用后，来自 KNX 总线的写入会立即更新节点本地缓存的 Hue 状态，无需等待 Hue Bridge 的反馈或事件。这样本地响应会更快，KNX 的即时读回也会更一致，尤其是在灯或分组灯关闭时。如果你希望缓存只跟随 Hue Bridge 的真实反馈/事件，请关闭此选项。 | |打开行为|打开时，它设置了灯的行为。您可以从不同的行为中进行选择。 **选择颜色：**将使用您选择的颜色打开灯。要更改颜色，只需单击颜色选择器（在选择颜色控制下）。 **选择温度和亮度： 您选择的温度（kelvin）和亮度（0-100）将打开灯。 none： 无：如果您启用夜间照明，夜间结束后，灯将恢复白天设置的颜色/温度/亮度状态。| |夜照明|它允许在夜间设置特定的浅色/亮度。选项与白天相同。您可以选择温度/亮度或颜色。舒适的温度为2700开Kelvin，亮度为10％或20％，是浴室夜灯的不错选择。 | |白天/夜|选择用于设置白天/夜行为的组地址。组地址值为_true_如果白天，_false_如果夜间。| |折叠白天/夜值|倒_日/夜间_组地址的值。默认值 未选中 。| |在启动时阅读状态|阅读启动时的状态，并在启动/重新连接时将事件发射到KNX总线上。（默认”否”）| |强制日间模式|您可以通过在此处描述的手动切换灯来强制进入日间模式：**通过快速关闭Ligth然后打开（仅此灯）**按描述执行，仅作用于这盏灯。**通过快速关闭Ligth然后打开（应用所有灯节点）**将所有灯节点切换到日间模式，并把昼/夜组地址设置为日间。| |节点输入/输出引脚|隐藏或显示输入/输出引脚。输入/输出引脚允许节点接受流量输入，并将MSG输出发送到流量。输入MSG必须遵循HUE API V.2标准。这是一个示例MSG，它打开光线： msg.on = {" on”：true} 。请参阅[官方HUE API页]（§URL0§）|

笔记

调光功能在** knx模式`启动``’’'’和st off’ 中起作用。要开始调暗，只发送一个”启动” knx电报。要停止调暗，请发送”停止” KNX电报。请 请记住**，当您设置墙壁时，请记住。

插座 / 输出 (plug)

Hue 插座 / Plug

概述

Hue Plug 节点将飞利浦 Hue 智能插座映射到 KNX 组地址，实现：

• 总线上的开/关控制；
• 来自 Hue 平台的状态反馈；
• 可选的 power_state（on/standby）监控。

配置

KNX 建议

• 控制与状态建议使用 DPT 1.xxx。
• power_state 可映射为布尔值（true=on, false=standby），或使用文本类 DPT 显示原始字符串。
• 接收到 KNX 读取 (GroupValue_Read) 时，节点返回缓存的 Hue 状态。

Flow 集成

当启用引脚时：

• 输入 ：发送 Hue v2 载荷（如 { on: { on: true } }）。
• 输出 ：在每次 Hue 事件时输出 { payload, on, power_state, rawEvent }。

Hue API

节点调用 /resource/plug/{id}。Hue 事件流用于捕获状态变化并同步到 KNX。

按钮 (button)

Hue Button 节点利用 button.button_report.event 将 Hue 按钮事件映射到 KNX，并在流程输出中提供相同的事件。

在 GA 输入框（名称或组地址）中键入即可关联 KNX GA；输入时会显示匹配的设备。

常规

开关

调光

行为

输出

1. 标准输出

   msg.payload 为布尔值或调光对象；msg.event 为 Hue 事件字符串（例如 short_release, repeat）。

详细信息

msg.event 对应 button.button_report.event，原始 Hue 事件包含在 msg.rawEvent 中。使用可选的状态 GA 可以让内部切换状态与墙壁开关等外部设备保持一致。

Tap dial (relative_rotary)

Hue Tap Dial 节点将 Tap Dial 的旋转服务映射到 KNX，并把原始 Hue 事件发送到 Node-RED 流程。配对新设备后，请点击设备字段旁的刷新图标。

选项卡

• 映射 - 选择旋转事件对应的 KNX 组地址和 DPT，支持 DPT 3.007、5.001、232.600。
• 行为 - 控制是否显示 Node-RED 输出引脚。未配置 KNX 网关时，引脚仍保持启用，以便事件继续进入流程。

常规设置

映射选项卡

输出

ℹ️ 仅在选择 KNX 网关后才会显示 KNX 相关控件；在同时配置好 Hue 网桥和 KNX 网关之前，映射选项卡会保持隐藏。

运动 (motion)

该节点订阅 Hue 运动传感器的事件，并将其同步到 KNX 以及 Node-RED 流程。

在 GA 字段输入 KNX 设备名称或组地址即可自动补全；”Hue 传感器”旁的刷新按钮可重新加载 Hue 设备列表。

常规

映射

行为

ℹ️ 未选择 KNX 网关时，KNX 字段会自动隐藏，可将节点用作纯 Hue → Node-RED 监听器。

输出

1. 标准输出 — msg.payload (boolean)

   侦测到运动为 true，运动结束为 false。

区域运动 (area_motion)

Hue 区域人体传感器节点订阅 Hue Bridge Pro 上 MotionAware 区域的聚合运动事件，并将“有人 / 无人”的结果同步到 KNX 或 Node-RED 流程。

在 GA 字段输入 KNX 设备名称或组地址即可完成绑定；输入时会显示匹配的建议。

常规

映射

行为

输出

1. 标准输出

   msg.payload (boolean)：当区域检测到运动时为 true，否则为 false。

详情

msg.payload 携带所选 MotionAware 区域的最新聚合运动状态。

摄像机运动 (camera_motion)

Hue Camera Motion 节点监听 Philips Hue 摄像头的运动事件，并将检测到/未检测到的状态映射到 KNX。

在 GA 输入框（名称或组地址）中开始输入，即可关联 KNX GA；输入时会显示匹配的设备。

常规

映射

输出

1. 标准输出

   msg.payload (布尔值)：检测到运动时为 true，否则为 false

详细信息

msg.payload 保存 Hue 摄像头服务上次报告的运动状态。

接触传感器 (contact)

该节点将 HUE 接触传感器事件映射到 KNX 组地址。

开始输入GA字段，KNX设备的名称或组地址，可用设备在输入时开始显示。

一般的

输出

1. 标准输出 ：有效载荷（布尔值）：命令的标准输出。

细节

msg.payload 为 HUE 事件（布尔/对象），可用于自定义逻辑。

光照度 (light_level)

该节点从 HUE 光照传感器读取 Lux 事件并发布到 KNX。

每当环境光变化时会输出 Lux 值。在 GA 字段输入 KNX 设备名或组地址（自动补全）以进行关联。

一般的

映射

输出

1. 标准输出

   payload (number)：当前 Lux 数值

细节

msg.payload 为数值型 Lux。

温度 (temperature)

此节点读取 HUE 温度传感器的温度（°C），并将其映射到 KNX。

在 GA 字段（名称或组地址）中输入以关联 KNX GA；输入时会显示设备建议。

一般的

映射

输出

1. 标准输出

   msg.payload（number）：当前温度（°C）

详情

msg.payload 包含数值型温度。

湿度 (humidity)

该节点从 HUE 湿度传感器读取相对湿度 (%) 并映射到 KNX。

在 GA 字段中开始输入（名称或组地址）以关联 KNX GA；输入时会显示匹配的设备。

常规

映射

输出

1. 标准输出

   msg.payload（数字）：当前相对湿度 (%)

详情

msg.payload 携带湿度的数值（百分比）。

场景 (scene)

Hue Scene 节点将 Hue 场景发布到 KNX，并且可以把 Hue 的原始事件发送到 Node-RED 流程。场景字段支持自动补全；在网桥中新增场景后，请点击刷新图标更新列表。

选项卡概览

• 映射 - 将 KNX 组地址与所选 Hue 场景关联。DPT 1.xxx 用于布尔控制，DPT 18.xxx 用于发送 KNX 场景号。
• 多场景 - 构建规则列表，将不同的 KNX 场景号映射到 Hue 场景，并选择 active / dynamic_palette / static 的调用方式。
• 行为 - 控制是否显示 Node-RED 输出引脚。未配置 KNX 网关时，引脚仍保持启用，以便桥接器事件继续进入流程。

常规设置

映射选项卡

多场景选项卡

ℹ️ 只有在选择 KNX 网关后才会显示 KNX 相关控件；在同时配置好 Hue 网桥和 KNX 网关之前，映射选项卡会保持隐藏。

电池 (device_power)

该节点会将 Hue 设备的电池电量同步到 KNX，并在数值变化时触发事件。

在 GA 字段输入 KNX 设备名称或组地址即可自动补全；点击”Hue 传感器”旁的刷新按钮可重新加载 Hue 设备列表。

常规

映射

行为

ℹ️ 未选择 KNX 网关时，KNX 映射字段会自动隐藏，便于将节点作为纯 Hue → Node-RED 事件源使用。

Zigbee 连接 (zigbee_connectivity)

该节点从 HUE 设备读取 Zigbee 连接状态，并发布到 KNX。

在 GA 字段输入 KNX 设备名或组地址，输入时会自动联想。

常规

映射

输出

1. 标准输出

   payload (boolean)：连接状态。

详情

msg.payload 为 true/false。
msg.status 为文本： connected, disconnected, connectivity_issue, unidirectional_incoming 。

设备软件更新 (device_software_update)

该节点监控 HUE 设备的软件更新状态，并发布到 KNX。

开始在GA字段中键入KNX设备的名称或组地址，可用的设备开始显示 您正在打字。

一般的

映射

输出

1. 标准输出

   payload (boolean)：更新标志。

   status (string)： no_update, update_pending, ready_to_install, installing 。