Philips Hue integration for Node-RED

HUE Ultimate is a standalone Philips Hue API v2 integration for Node-RED. Control lights, groups, plugs and scenes, receive button and sensor events, and connect everything through ordinary Node-RED messages.

The package does not require KNX. Enable the node pins, use msg.topic for the selected function and carry its value in msg.payload. If your installation also uses KNX Ultimate, you can optionally select its gateway and map the same functions directly to group addresses and DPTs.

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.

Installation

Requires Node.js >=20.18.1 and Node-RED >=3.1.1.

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.

Optional KNX integration

Install node-red-contrib-knx-ultimate and select its gateway only when you want native KNX mapping. The same 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.