When adding a KNX IP integration, after entering the IP address of the IP interface you will be prompted to visit the configuration loader web page. The CSV project export from KNX can't directly be used to configure Rithum Switch. Instead, the configuration data needs to be presented in a specific YAML format in order to pass the configuration to the switch.
The YAML text needs to be copied/pasted into the form on the web page followed by pressing "Load Configuration".
See the Release Notes for the KNX IP plugin here.
The Configuration Format
If you’re new to YAML then please read this first: What is YAML?
A basic example configuration is as follows.
Note that any text after a # is a comment and is ignored
---
version: 1.0
connection:
type: UDP
zones: zone1: name: Demo Room commands: cmd1: name: Scene 1 group_address: 0/0/1 type: scene_number value: 1 cmd2: name: Scene 2 group_address: 0/0/1 type: scene_number value: 2 cmd3: name: Scene 3 group_address: 0/0/1 type: scene_number value: 3
cmd4:
name: Turn On
group_address: 0/0/2
value: on
cmd5:
name: Scene 5
group_address: 0/0/1
type: scene_number # For scene recall, use scene_number
value: 5
cmd6:
name: Boolean Example # For boolean e.g. switch, omit type
group_address: 0/1/0
value: on # Boolean supports true/false, on/off, or yes/no
cmd7:
name: Binary/Dimming Ex. # For binary e.g. dimming omit type
group_address: 0/1/2
value: 255 # Range of 0-255
cmd8:
name: Percent Example
group_address: 0/1/8
type: percent # Percent type
value: 25 # Range of 0-100
cmd9:
name: Temp Example
group_address: 0/2/0
type: temperature # Temperature type
value: 21 lights: light1: name: Dimmer 1 group_address_switch: 0/1/0 group_address_switch_state: 0/1/1 group_address_brightness: 0/1/3 group_address_brightness_state: 0/1/4 light2: name: Dimmer 2 group_address_switch: 0/1/5 group_address_switch_state: 0/1/6 group_address_brightness: 0/1/8 group_address_brightness_state: 0/1/9 temperature_feed: group_address: 0/2/0
A description of the fields are as follows:
version
- must be present and set to 1.0
connection
- optional object containing IP connection details, currently just the following field:
type
- mandatory, UDP
orTCP
depending on the protocol used by the IP interface.
Note: if the connection object is not included then the connection will default to TCP.
zones
- A collection of zone objects keyed on a unique string ID
A description of the zone object fields are as follows:
name
- mandatory, string for the label to be shown for the zone/room/area.
commands
- optional, a collection of command objects keyed on a unique string ID. These command objects allow any value to be written to a specified group address. These commands can then be selected for use in scene buttons, for hold gestures or for Rithum Stat heating actions.
The command object fields are as follows:
name
- mandatory, string for the main label to be shown on the scene button.
group_address
- mandatory, the KNX group address to write a value to.
type
- optional, depending on the value to be written.
value
- mandatory, value to be written.
For DPT-1 (boolean), e.g. switch, omit type
and use any valid YAML boolean for value
- true/false, on/off, or yes/no
For DPT-2 & DPT-3 (binary), e.g. dimming control, omit type
and use the required integer binary value for value
i.e. 0-255
For other DPT types a named type should be specified for type
, eg. percent
, temperature
or scene_number
with a corresponding valid value for value
. A complete reference of valid value types is available here: DPT value types reference
lights
- optional, a collection of light objects keyed on a unique string ID. These light objects represent each lighting circuit within a zone. A zone containing lights can be selected for inclusion in the Levels screen. The Levels screen control for the zone can then be used to control all lights in the zone, or expanded to control individual lights. Also, "Turn On", "Turn Off" and "Toggle" actions for all lights in the zone will be available for use as Scene buttons. "Toggle All" can also be selected for the standby screen 'hold' gesture.The light object fields are as follows:
name
- mandatory, string for the label to be shown in the Levels screen.
group_address_switch
- mandatory, group address to turn the light on/off.group_address_switch_state
- mandatory, group address for light on/off feedback.group_address_brightness
- optional, group address to set the light brightness.group_address_brightness_state
- optional*, group address for light brightness feedback. temperature_feed
- This optional object has a single field, group_address
which can be used to specify a group address that Rithum Switch will send current temperature readings to (in °C). Note that the temperature_feed
object is at the top-level of the data structure, it is not associated with a particular zone.Modifying Configuration
In the settings menu, navigate to Integrations, select the KNX IP integration then press Edit. Press the tick if the IP address is the same. You will then be prompted again to visit the configuration loader web page where the process of pasting the YAML configuration data can be repeated. Press Skip to skip replacing the existing configuration if required.
The simple configuration data example is attached to this article which can be used as a starting template.
Recommendations
- Save configuration data to file for future use/modification
- Use a plain text editor such as Sublime Text or Visual Studio Code to edit the YAML data.
- To minimise unnecessary comms, only configure lighting zones which are required for each switch rather than configuring all switches with all available zones
Comments
0 comments
Please sign in to leave a comment.