KNX is one of the main european standard used for home and building automation, and historically the first driver supported by our Weble software. KNX devices can manage lighting, blinds and shutters, HVAC, security systems, energy management, audio video, white goods, displays, remote control, etc.. The universal IoT gateway can connect to the KNX bus either directly on the KNX twisted pair with the S485-KNX model, or for hardware not supporting the KNX connector through a KNX IP router or a KNX USB interface. The Weble KNX gateway driver is very thorough and versatile. It can play multiple roles for different use cases such as :
- Reading / writing values on the KNX bus as a home supervisor or a gateway between protocols.
- Programming of automatisms for your home using the logic module.
- Act as a KNX device on the KNX bus by replying to KNX read / write requests, can be used to broadcast periodically some data on the KNX bus.
- Custom routing / filtering between different KNX lines for big KNX projects.
- Acting as a standard KNX IP router, with the additional possiblity to connect remotely to the KNX line of the installation through a VPN connection. It is very useful for remote maintenance and programming of the KNX devices with the ETS KNX software.
¶ 1. Getting started
Once connected on the KNX bus, the driver decodes knx paquets travelling on the line and communicating KNX addresses can be automatically added in the gateway. The KNX addresses can also be imported using the "Import file button" and selecting the ETS exported configuration files.
¶ 2. Gateway
The gateway can act directly on the bus if the hardware has a KNX twisted pair, or through a USB-KNX interface, but it can also connects to a KNX IP router. The gateway can also at the same time act as a KNX IP router, enabling remote connection to the site with the ETS KNX configuration software.
| Label | JSON Key | Description |
|---|---|---|
| Mode | mode | Define the mode of connection: tp: Twisted Pair (via local port if exists) usb: USB (via KNX USB gateway)ipt: IP Tunneling (via KNX IP gateway)iptn: IP Tunneling NAT (via KNX IP gateway) behind NAT (Network address translation)ip: IP multicast (via multicast KNX) |
| Host | host | Only applies to IP connection modes. It is the IPv4 ip address of the KNX ip router for ipt and iptn modes. for the ip mode, it is a multicast IP address like 224.0.23.12. |
| Port | port | Only applies to ipt and iptn modes. The IP port used to connect to the KNX ip router. |
| Write delay | writeDelay | Define a delay in milliseconds between each packets sent to the bus. Writing packets sequentially without pauses can lead to packets loss depending on the connection mode and infrastructure. The default value is 200ms. |
| Default address format | groupFormat | The format used to represent KNX group addresses. Possible values are 3-level,2-level, and Free-level. The different formats are explained in the next document section. |
| Auto insert address | autoInsertAddress | Specifies wether the group addresses communicating on the BUS are automatically inserted in the gateway or not (true or false). |
| Auto insert device | autoInsertDevice | Specifies wether the participant/device addresses communicating on the BUS are automatically inserted in the gateway or not (true or false). |
| EIB Address | address | The desired KNX participant address of the gateway, if it applies depending on the connection mode and the infrastructure. |
| Server | server | Acts as a KNX IP router by allowing clients to connect (true or false). |
| EIB Client range | clientAddresses | Only applies if the Server parameter is true. The range of KNX participant addresses given to the KNX router clients. Example : 15.15.251:4 can assign addresses 15.15.251, 15.15.252, 15.15.253, and 15.15.254 to maximum 4 clients. |
| Server port | serverPort | Only applies if the Server parameter is true. Defines the IP port on which the KNX server communicates. |
| ETS | serverETS | Only applies if the Server parameter is true. Allows or not (true or false) ETS, the KNX configuration tool, to communicate on the bus in order to program the devices. |
| Multicast server | serverMulticast | Only applies if the Server parameter is true. Forwards the KNX packet received from the bus to the multicast ip address, and forwards KNX packet received on the multicast ip address to the bus. |
| Multicast ip | serverMulticastAddress | Only applies if the Multicast server is true. Defines the multicast address on which the KNX server communicates. Note that the multicast port is fixed to 3671. |
¶ 3. Addresses
There is two types of KNX addresses, the group addresses and the participants addresses.
-
Group addresses : these addresses are used to address values sent by the participants over the KNX bus. Multiple participants can communicate / use on the same group address. There is 3 possible notations for group addresses :
- 3 level notation :
[main]/[middle]/[sub]such as29/4/243
main = D7+D6+D5+D4+D3 of the first octet (high address)
middle = D2+D1+D0 of the first octet (high address)
sub = the entire second octet (low address)
ranges: main = 0..31 (5 bits), middle = 0..7 (3 bits), sub = 0..255 (8 bits) - 2 level notation :
[main]/[sub]such as29/1267
main = D7+D6+D5+D4+D3 of the first octet (high address)
sub = D2+D1+D0 of the first octet (high address) + the entire second octet (low address)
ranges: main = 0..31 (5 bits), sub = 0..2047 (11 bits) - Free level notation (1 level) :
%knx:[main]such as%knx:60659
main = raw integer coded on all 16 bits
ranges: main = 0..65535 - Example :
29/4/243,29/1267, and%knx:60659all resolve to the same group address using the 3 different formats.
- 3 level notation :
-
Device addresses: this the physical addresses of KNX devices, also called participant addresses. This device address has 3 levels seperated by dots.
[main].[middle].[sub]such as15.15.251. The first part ranges from 0-15 (4 bits), the second part ranges from 0-15 (4 bits), and the third part ranges from 0-255 (8 bits). So the address is encoded over a total of 16 bits.
¶ 3.1 Group address parameters
The group addresses are mainly used to send commands over the bus, or to communicate sensor data such as temperatures, wind speed, or energy meters total kWh, and so on.
The following parameters are supported for group addresses :
| Label | JSON Key | Description |
|---|---|---|
| Datatype | datatype | The KNX protocol has several predefined data point types (DPT) for encoding and decoding values. Here is the reference document for datatypes: knx_datatypes.pdf. Most commonly used encodings are supported by this driver, and potentially missing ones can be added on customer demand. |
| Read | read | This parameter defines if the group address needs to be read regularly (polling). It can be the polling delay in milliseconds such as 60000 to send a read request/packet on the bus every minute. If no polling is desired, the value should be left empty or set to never. If the values needs to be read only at the driver startup, the value startup can be set. If the IoT gateway is the one that should respond to read requests on this group address, then the value respond has to be configured. |
| Write | write | This parameter defines if the group address needs to be written regularly or not. It can be a periodic event defined in milliseconds such as 60000 to send a write packet on the bus every minute. This parameter is used to send cyclically packets on the bus such as sensor data or watchdogs. When this parameter is configured, the Read parameter should usually be set to respond. |
| Watchdog | watchdog | This parameters can be either milliseconds or a cron text. It checks periodically if the address has communicated on the bus, and if it has not communicated it checks wether it replies or not to a read request. If the address has not communicated and did not reply to the read request, then the status of the address changes to !watchdog. The minimum milliseconds value is 60000 (1 minute). |
| Store value | remanent | Can typically be configured to store the last value of a group address to which the knx driver responds to (Read parameter set to respond). If the values are not stored on the disk, they are lost after the system reboot. Store values : "never", "always", or a delay in milliseconds such as 60000 to save the address value on the disk every minutes. |
¶ 3.2 Device Address parameters
The device addresses are usually not used, except for setting up watchdogs on certain devices to know if the check if the device communicates on the bus or not. If not this can be useful to send alerts.
| Label | JSON Key | Description |
|---|---|---|
| Watchdog | watchdog | This parameters can be either milliseconds or a cron text. It checks periodically if the device address has communicated on the bus, and if it has not communicated it checks wether it replies or not to a read request of its device information and version. If the device has not communicated and did not reply to the read info request, then the status of the address changes to !watchdog. The minimum milliseconds value is 60000 (1 minute). |