Native Matter integration with KNX Ultimate

Matter Ultimate extends KNX Ultimate with native Matter integration. It carries forward the Matter functionality originally included in KNX Ultimate as a dedicated package, connecting your KNX installation with the Matter ecosystem.

Its purpose is to serve the KNX Ultimate ecosystem, not to replace or compete with existing general-purpose Matter nodes for Node-RED. Select your KNX Ultimate gateway to map commands and feedback directly to KNX group addresses and DPTs, with suggestions from your imported ETS project.

Use Matter Controller to control Matter devices from KNX, or Matter Bridge to expose KNX devices to Matter apps. Both nodes share the gateway already configured in KNX Ultimate.

The nodes support 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.

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-matter-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-matter-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, in Matter Controller 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.

Controller 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. Command and state mappings keep their existing direction: for Matter Bridge, status-topic inputs update the virtual device and Matter commands appear on the configured command-topic outputs.

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.

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.