node-red-contrib-hue-ultimate 1.0.0-beta.3
Native Philips Hue integration with KNX Ultimate for Node-RED: connect Hue lights, scenes and sensors directly to KNX group addresses through one multimode Controller.
Native Philips Hue integration with KNX Ultimate
HUE Ultimate extends KNX Ultimate with native Philips Hue integration. It carries forward the Hue functionality originally included in KNX Ultimate as a dedicated package, keeping Hue commands and feedback directly connected to your KNX installation.
Its purpose is to serve the KNX Ultimate ecosystem, not to replace or compete with existing general-purpose Hue nodes for Node-RED. Select your KNX Ultimate gateway to map Hue functions to KNX group addresses and DPTs, with suggestions from your imported ETS project.
One multimode HUE Controller handles lights, groups, plugs, scenes, buttons and sensors. Choose a Hue resource and the node shows its supported functions. Controllers share a Hue Bridge configuration.
The node supports standard Node-RED messages: msg.topic identifies the function and msg.payload carries its value. KNX Ultimate is required only for KNX mode; message-based flows work without a KNX gateway.
📘 Go to documentation (English)
📘 Vai alla documentazione (Italiano)
📘 Zur Dokumentation (Deutsch)
📘 Accéder à la documentation (Français)
📘 Ir a la documentación (Español)
📘 前往文档（简体中文）
Installation
Requires Node.js >=20.18.1 and Node-RED >=3.1.1. This is the first public beta, available to everyone.
In Node-RED, open Manage palette → Install, search for node-red-contrib-hue-ultimate and install it. Restart Node-RED.
Alternatively, run this command in your Node-RED user directory (usually ~/.node-red):
npm install node-red-contrib-hue-ultimate
Using Node-RED messages
Enable the input/output pins and enter topic names in the command and state fields. Leave the KNX gateway empty; DPT fields are hidden because they are not needed. Use separate command and state topics. Matching is exact; wildcards are not supported.
For example, enter living-room/brightness in the brightness command field and send:
msg.topic = "living-room/brightness";
msg.payload = 60;
return msg;
Use booleans for on/off, percentages for brightness, Kelvin for color temperature, and {red, green, blue} for RGB. Relative dimming uses the existing {decr_incr, data} value shape. Scene recall accepts the configured scene number (or a boolean for a single scene).
Configured state fields publish their values with the configured topic and msg.payload. Existing RAW messages remain supported, and RAW events remain available alongside mapped state messages.
KNX mode
Native integration with KNX Ultimate is the core purpose of this package. Install node-red-contrib-knx-ultimate and select its gateway to enable KNX mode. The same mapping fields then use group addresses and DPTs, with suggestions from the imported ETS project. Commands and feedback pass directly over the bus; no intermediate Function node is needed for these mappings.
When selecting a gateway, replace the saved topics with real group addresses and choose the correct DPTs. A selected gateway that is offline leaves the node in KNX mode. To return to Node-RED messages, clear the gateway and configure the topics again.
Existing flows
On editor startup, the package looks for its legacy nodes and configuration nodes. It offers Later or Back up and convert. Nothing changes until you choose conversion. The conversion downloads a flow backup, preserves node IDs, wires, settings and configuration references, and creates one undo operation. Review the result before pressing Deploy.
All fifteen dedicated HUE node types from KNX Ultimate become HUE Controllers with the matching function. The old multimode HUE Controller keeps its selected function. Shared Hue Bridge configurations are converted too, with their IDs and credentials preserved.
Migrate and Deploy with KNX Ultimate 7 still installed, before upgrading it to version 8. Keep KNX Ultimate installed if you use KNX mappings. The two packages use distinct public node types and admin routes and can run together. See migration details.
Examples
Importable examples explain setup and cover Node-RED messages and the optional KNX mode. The JSON files are also in examples/.
Development
npm install
npm test
npm pack
Hardware pairing and physical device operation still need validation on the intended installation before a stable release.
