node-red-contrib-knx-ultimate/tutorial/knxUltimate.md

Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control and ETS group address importer. Easy to use and highly configurable.

# knxUltimate Node – Tutorial Outline

## 1. Intro (0:00)
- "Hi everyone! In this video we’re exploring the `knxUltimate` node, the bidirectional KNX device node from the `node-red-contrib-knx-ultimate` palette."
- "We’ll learn how to subscribe to KNX group addresses, send telegrams, and customise the behaviour for different datapoint types."

## 2. When to Use It (0:25)
- "Use `knxUltimate` whenever you need a Node-RED node to listen to or control a KNX group address."
- "It supports read, write, and response telegrams and can optionally listen to multiple addresses at once."

## 3. Inputs and Outputs (0:45)
- "One input: accepts Node-RED messages to send onto the KNX bus."
- "One output: emits messages when KNX traffic matches the configured address and filters."
- "Optional status icons indicate RBE (Report by Exception) filtering on input or output."

## 4. Core Configuration (1:10)
- **Server**: select your `knxUltimate-config` gateway.
- **Topic (Group Address)**: the GA to monitor or control, for example `1/2/3`.
- **Set Topic Type**: `str` for a single GA, `listenAllGA` for the universal listener, or `manual` for advanced arrays.
- **Output Topic Override**: set a different topic for outbound messages if needed.
- **DPT (Datapoint Type)**: choose the datapoint so values are encoded/decoded correctly.
- **Name**: friendly label shown in flows.

## 5. Communication Behaviour (1:55)
- **Initial Read**: set to `0` to skip, `1` or `2` to issue automatic read requests at deploy.
- **Notify Flags**: enable `notify read request`, `notify response`, and `notify write` depending on which telegram classes you want forwarded to the output.
- **Auto Respond to Read**: tick `Notify read request also respond to bus` to send the node’s last value back automatically, and set a default value if there is no cached payload yet.
- **Read/Write Modes**: `output type` can be `write`, `response`, or `read`. Pair with `passthrough` to echo inbound payloads back to the flow when desired.

## 6. Filtering and Formatting (2:35)
- **Output RBE / Input RBE**: suppress repeated values on either side of the node.
- **Numeric Formatting**: multiply by a factor, clamp negative numbers (leave/absolute/zero), and specify decimal precision before the value is sent downstream.
- **Listen All GA**: when enabled, the node emits any telegram that hits the bus; combine with function hooks to filter programmatically.

## 7. Function Hooks & Snippets (3:10)
- **Send Message to KNX**: optional JavaScript executed before sending telegrams; perfect for validation or payload transformation.
- **Receive Message from KNX**: optional JavaScript that runs on incoming telegrams so you can enrich metadata or filter.
- **Snippet Pickers**: use the built-in dropdowns for common payload patterns (`Switch`, `Dim`, `Color`, etc.).
- **Sample Editor**: choose a DPT and open the help drawer to see documentation and example payloads.

## 8. Secure Group Addresses (4:00)
- "If the linked `knxUltimate-config` node has a keyring loaded, the GA field highlights addresses flagged as secure."
- "The node icon switches automatically to the secure shield variant when `GA Secure` is set."

## 9. Best Practices (4:20)
- "Always match the DPT to the device; wrong datapoint conversion leads to garbled payloads."
- "Use RBE filters to reduce chatter if the device polls frequently."
- "Prefill the default response value so group read requests receive meaningful data after a restart."

## 10. Example Workflow (4:50)
- "Demo: read a temperature sensor (DPT 9.001) and mirror it to an MQTT topic."
- "Demo: toggle a light with a simple inject node, using the `send message` function hook to clamp booleans."

## 11. Wrap-Up (5:20)
- "We configured the KNX device node, tuned its notification options, and added custom JavaScript hooks."
- "In the next tutorial we’ll look at another node from the suite and continue building out our KNX dashboard." 

## 12. Call to Action (5:40)
- "Like, subscribe, and leave KNX scenarios in the comments so I can cover them in upcoming videos."