node-red-contrib-knx-ultimate/tutorial/knxUltimate-config.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-config Tutorial Outline

## 1. Intro (0:00)
- "Hi everyone, welcome back! In this video we’ll configure the `knxUltimate-config` node, the central KNX gateway for the `node-red-contrib-knx-ultimate` palette. We’ll walk through every option so you can tailor your gateway exactly to your installation."

## 2. Prerequisites (0:20)
- "You’ll need Node-RED 2.1 or newer, the `node-red-contrib-knx-ultimate` package installed, and basic KNX/IP gateway details: host, port, individual address, and—if you plan to run secure—your ETS keyring XML plus tunnel credentials."

## 3. Opening the Config Node (0:40)
- "Drag any KNX Ultimate node into the flow, double-click it, and look at the ‘Server’ dropdown. Click the pencil icon next to it. That opens the `knxUltimate-config` editor we’ll configure now."

## 4. Overview of the Editor Layout (0:55)
- "The editor is split into sections: the general connection settings, the secure / unsecure tab selector, extra configuration tabs (Configuration, Advanced, ETS Import, Utility), and helper buttons along the way. Let’s start with the core connection block at the top."

## 5. General Gateway Settings (1:15)
- **Name**: "Set a friendly name so you can recognize this gateway in node dropdowns."
- **Gateway Host**: "Enter the IP or hostname. Type ‘EMULATE’ if you’re demonstrating without a real gateway."
- **Refresh Button**: "Click the green refresh icon to discover KNX/IP interfaces on the network. It populates the host field, port, device name, protocol, and reveals how many devices were found."
- **Interface Binding**: "Choose the local Ethernet interface from the dropdown. Leave ‘Auto’ to let the node auto-detect based on subnet. Select ‘Manual’ if you need a different interface and supply the name just under it."
- **Port**: "Default is 3671. Change it only if your gateway uses a custom port."
- **Protocol**: "Choose between UDP tunnel, TCP tunnel, or multicast. The node auto-locks this when you pick a discovered device; you can still override it manually if needed."
- **Physical Address**: "Assign the individual address you want this gateway to use. The node generates a sensible suggestion when it knows your gateway’s address."

## 6. Secure vs Unsecure Tabs (2:10)
- "The `tabsMain` widget switches between plain KNX (left tab) and KNX Secure (right tab). The secure tab adds extra controls for the keyring, tunnel credentials, and secure hints. Toggle between them to match your gateway’s capabilities."

## 7. Secure KNX Section (2:30)
- **YouTube link**: "Click the red link to watch a quick tutorial on exporting the keyring."
- **Secure Credentials Mode**: "Select `keyring`, `manual`, or `combined`. This controls which fields appear below."
  - **Keyring Mode**: "Paste the ETS Keyring XML into the editor. For quick edits there’s a full Monaco editor with line wrapping but no minimap or line numbers."
  - **Password Field**: "Enter the keyring password; leave blank if the keyring is not protected."
  - **Tunnel IA Selection**: "Choose Auto or Manual. Manual exposes the text field for the tunnel individual address."
- **Manual or Combined Mode Extras**: "If you choose manual or combined, additional fields appear for tunnel IA, tunnel user ID, and password."
- **Auto-Bind Info**: "When you save, the node calculates the correct tunnel protocol and interface. Matching subnet detection happens automatically if the interface selection is left to Auto."

## 8. Additional Tabs (3:20)
- **Configuration Tab**:
  - "Delay Between Telegrams: defaults to 25 ms, clamp between 25–100. Use this to throttle outgoing traffic."
  - "Ignore repeated telegrams, suppress ACK requests, and other toggles for bus behavior."
- **Advanced Tab**:
  - "Log level options, queue settings, and options for exposing the gateway status as a global context variable."
- **ETS Import Tab**:
  - "Paste CSV or ESF exports here—the Monaco editor is ready for large files with the minimap removed for clarity. Configure failure behavior for missing datapoints."
- **Utility Tab**:
  - "Buttons to gather debug info, list all used group addresses, and access key troubleshooting tools."

## 9. Auto-Discovery and Interface Selection Tips (4:10)
- "When you type a plain IP address, the protocol dropdown unlocks so you can choose UDP, TCP, or multicast. If you select a gateway from discovery, the node locks the protocol to the one reported by the device. The interface dropdown auto-fills with the best match against the gateway’s subnet—override only if necessary."

## 10. Saving the Configuration (4:35)
- "Click ‘Done’ to close the dialog, then deploy your flow. On deploy, the node validates keyring data and, if you populated a CSV or keyring, prompts with a modal reminder that ETS data will be processed."

## 11. Status Indicators (4:50)
- "In the flow editor, the config node shows status: green for connected, yellow for waiting or initializing, red for errors. The node logs detailed messages—you can adjust verbosity under Advanced -> Log Level."

## 12. Best Practices & Tips (5:10)
- "Keep the keyring editor clean—paste only the XML exported by ETS."
- "Use manual interface binding only when the automatic match picks the wrong adapter, for example in multi-homed systems or VPN scenarios."
- "If you switch between secure and non-secure modes, double-check the protocol and port, because some gateways require different ports for secure tunnels."

## 13. Wrap-Up (5:40)
- "That’s the `knxUltimate-config` node. We configured the host, interface binding, secure credentials, and walked through the supporting tabs. In the next tutorial we’ll explore the standard `knxUltimate` I/O node and see how it consumes this configuration."

## 14. Call to Action (5:55)
- "If you found this helpful, give it a like and subscribe. Drop questions or scenarios in the comments—I’ll cover them in future videos. See you in the next walkthrough!"