node-red-contrib-knx-ultimate/tutorial/knxUltimateHATranslator.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.

# knxUltimateHATranslator Node – Tutorial Outline

## 1. Intro (0:00)
- "Hi! Let’s configure the `knxUltimateHATranslator`, a handy bridge between Home Assistant phrases and KNX boolean payloads."
- "It converts strings like `on`, `open`, or `home` into `true/false` values ready for KNX telegrams."

## 2. Typical Use Cases (0:25)
- "Translate Home Assistant automation outputs into KNX-friendly payloads."
- "Normalize voice assistant commands or MQTT messages before they reach the `knxUltimate` node."

## 3. Inputs & Outputs (0:45)
- "One input, one output."
- "Incoming messages are modified in-place (or under a custom property) and passed through."

## 4. Core Configuration (1:00)
- **Name**: optional label for the workspace."
- **Input Property**: defaults to `payload`; set another path if your commands arrive in `msg.data` or `msg.value`."
- **Translation Table**: edit the multi-line editor where each row is `incomingValue:outgoingValue`."
  - Default entries map `on`→`true`, `off`→`false`, `open`→`true`, `closed`→`false`, `1`→`true`, `0`→`false`, etc.

## 5. How Translation Works (1:45)
- "Incoming value is coercively converted to string and compared line by line (case-insensitive)."
- "If a match is found, the node replaces the property with the mapped value, preserving booleans, strings, or numbers."
- "If no match, the message passes untouched, so add catch-all rows where needed."

## 6. Editing Tips (2:15)
- "Use one mapping per line."
- "You can map to complex JSON by wrapping the target in quotes and parsing downstream if needed."
- "Comment lines with `#` for documentation (ignored by the parser)."

## 7. Workflow Examples (2:40)
- "Example: convert Home Assistant binary sensor states to KNX binary outputs."
- "Example: map presence detection values (`home`/`not_home`) to boolean flags used by KNX logics."
- "Example: convert dimmer commands `on`, `off`, `close` into boolean pulses for KNX shutters."

## 8. Best Practices (3:10)
- "Keep the table sorted or grouped for clarity."
- "Use the translator early in your flow so the rest of the pipeline receives consistent data types."
- "Combine with the `knxUltimateAutoResponder` to backfill defaults for virtual devices."

## 9. Wrap-Up & CTA (3:30)
- "We renamed the input property, adjusted the translation table, and tested conversions."
- "Like, subscribe, and comment with Home Assistant phrases you want to translate next!"