Declarative EIB/KNX client for ease of bridging between KNX and other home automation specifications. Declaration is done via simple YAML file. The KNX Bridge client runs as a daemon, assuring data transfer (r/w) and data transformation without the need for one line of code.
KNXBridge is for all home automation enthusiasts which are:
- have their own custom KNX home automation and seek an easy setup and easy maintenance solution in comparison to openHab, ioBroker, Home-Assistant, and alike without the need for a graphical representation
- have a commercial KNX home automation like Hager, MDT, and alike and want to integrate custom components via the KNX bus to circumvent vendor-lockin
KNXBridge is centered around KNX but also provides general bridging functions, e.g routing messages from ModBus to MQTT. General KNX as well as associated appliance understanding to define endpoints and datatypes is required.
- Running KNXD daemon for communication with the KNX bus
- The EIB/KNX Client as the Python-interface with KNXD
- The Python3-ified version of pKNyX for transformation of KNX Datapoint Types (DPT)
git clone https://github.com/MBizm/KNXBridge
cd src
./register_daemon.sh
KNX Bridge will be executed as a daemon service. Configuration will be taken from ~/.knx/bridge/CONFIG.yaml. The daemon needs to be restarted everytime the configuration changes via sudo systemctl restart KNXBridgeDaemon.
The configuration file declaring the client and their respective attributes to be exchanged is located in ~/.knx/bridge/CONFIG.yaml. Folder and initial configuration template will be created by installation script.
- Section - general configuration for KNXBridge service: General KNXBridge service related configuration like logging level. all configuration values start with config*.
- Section - appliances/gateway definitions: List of defined appliance/gateways. Multiple instances of the same appliance/gateway type can be defined and are identified by their unique ID. An appliance is a physical device in the real world either being directly available via a TCP-based network(e.g. ModBus via TCP) or a gateway acting an intermediate translator for the actual devices (e.g. ZigBee gateway).
- Section - physical device and attributes definition: List of physical devices and attributes which are supposed to be monitored or updated based on either changes in the physical device or the KNX bus.
For reference of all attributes and template of the whole configuration file refer to template configuration file.
configSet: Optional Title for your configuration file
configNote: >
Optional detailed description and remarks for your configuration file
configVersion: 0.5 # format version of config file
configVerbose: "info" # log level - "off", "error", "warning", "change", "info"
| Specification | Querying procedure | Remark |
|---|---|---|
| ModBus | Polling with frequency defined via updFreq attribute | -- |
| ZigBee | Polling via the deConz ZigBee Gateway Rest API with frequency defined via updFreq attribute | -- |
| MQTT | Listening to defined MQTT broker instance with immediate update to the KNX bus. | Watch out: high frequency update of MQTT clients might flood your KNX bus!! |
| KNX | KNXDaemon can register as a listener for a KNX address and route the value to another target address. Optional: polling frequency may be defined via updFreq attribute in addition to listening to src address | -- |
knxdAppliance:
knxdIP: <ENTER YOUR IP HERE>
modbusAppliance:
- modbusApplID: 0
modbusName: "Solar Inverter"
modbusIP: <ENTER YOUR IP HERE>
modbusPort: "1502"
The ZigBee gateway acts as a multiplexer for multiple physical devices. Configuration is therefore two-folded by configuration of gateway and the actual physical zigbee device.
deConz Gateway configuration:
deconzAppliance:
deConzIP: <ENTER YOUR IP HERE>
deConzPort: <ENTER YOUR PORT HERE>
deConzToken: <ENTER YOUR AUTH TOKEN HERE>
ZigBee appliance configuration:
zigbeeAppliance:
- zigbeeApplID: 1001a
zigbeeName: "Smart Things Garage Gate - Closing State"
deConzID: 2
deConzType: "sensors"
mqttAppliance:
- mqttApplID: 100
mqttName: "MQTT Broker Instance"
mqttIP: <ENTER YOUR IP HERE>
mqttPort: "1883"
mqttUser: "myUser"
mqttPasswd: "myPasswd"
The definition of all physical devices and attributes independent of their appliance type is listed under the attributes section, each physical device or attribute representing one YAML block item. The corresponding appliance ID (e.g. modbusApplID, zigbeeApplID) links the physical device or attribute to the corresponding appliance.
Some components (can be also called YAML block items) are shared across appliance types:
| Component | Purpose | Reference |
|---|---|---|
| name (obligatory) | String explanation of attribute, mainly for YAML readability as well as logging purpose | -- |
| knxAddr (obligatory) | KNX address in XXX/YYY/ZZZ representation; for all KNX write actions (e.g. modbus2knx) this defines the target the value shall be written to, for all KNX read actions (e.g. knx2knx) this defines the source the value shall be retrieved from | -- |
| knxFormat (obligatory) | DPT representation which defines how the KNX bus expects the value to be represented / value from the KNX bus shall be interpreted. The DPT is supposed to defined in the full DPT value definition, e.g. "14.077", "1.002". Carefully check the DPT type expected for the specific scenarios, e.g. some vendor write "1.001" Switch Value with corresponding values "On"/"Off" while actually expecting "1.002" Boolean Value with corresponding values "True"/"False". | KNX DPT Definition |
| updFreq (obligatory for some appliance types) | Defines the time interval the value shall be checked for changes; this applies to appliances which are polled only (e.g. ZigBee, ModBus). Optional polling is also enalbed for KNX devices. | -- |
| function (optional) | Set of transformations that can be performed before the value is written to its destination. | Functions implementation docu |
- name: "Current AC Power"
type: "modbus2knx"
modbusApplID: 0
modbusAddrDec: 100
modbusFormat: "float"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "14.056"
updFreq: "very high"
- name: "Current Power Consumption"
type: "modbus2knx"
modbusApplID: 0
modbusAddrDec: [106, 108, 116] #aggregation of ModBus attributes
modbusFormat: "float"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "14.056"
updFreq: "very high"
- name: "Current AC Power - MQTT"
type: "modbus2mqtt"
modbusApplID: 0
modbusAddrDec: 100
modbusFormat: "float"
mqttApplID: 100
mqttTopic: "/PV/CurrentACSolar"
updFreq: "very high"
Given example is from a Samsung SmartThings gate control, a Devolo smoke alarm device, and a Paulmann light panel
- name: "Garage Gate Closing State"
type: "zigbee2knx"
zigbeeApplID: 1a
zigbeeAttr: "open"
zigbeeFormat: "boolean"
function: "inv()"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.002"
updFreq: "very high"
- name: "Garage Gate LowBattery"
type: "zigbee2knx"
zigbeeApplID: 1b
zigbeeAttr: "battery"
zigbeeFormat: "int"
zigbeeSection: "config"
function: "lt(10)"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.002"
updFreq: "low"
- name: "Living Room Fire"
type: "zigbee2knx"
zigbeeApplID: 2a
zigbeeAttr: "fire"
zigbeeFormat: "boolean"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.002"
updFreq: "very high"
- name: "TER NoConnection"
type: "zigbee2knx"
zigbeeApplID: 2a
zigbeeAttr: "lastupdated"
zigbeeFormat: "date"
function: "timedeltaGT(900)"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.002"
updFreq: "medium"
- name: "Light Paneel on/off"
type: "knx2zigbee"
zigbeeApplID: 3a
zigbeeAttr: "on"
zigbeeFormat: "boolean"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.002"
- name: "Light Paneel brightness"
type: "knx2zigbee"
zigbeeApplID: 3a
zigbeeAttr: "bri"
zigbeeFormat: "int"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "5.004"
- name: "Light Paneel COLOR"
type: "knx2zigbee"
zigbeeApplID: 3a
zigbeeAttr: "xy"
zigbeeFormat: "list"
function: "rgb_2_xy()"
knxAddr: '[<KNX_RED>,<KNX_GREEN>,<KNX_BLUE>]'
knxFormat: "5.001"
- name: " Waterflow sensor"
type: "mqtt2knx"
mqttApplID: 100
mqttTopic: "/waterflow"
mqttFormat: "float"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "14.077" # liter/sec
- name: "Solar Extra Production" # PV Mehrerlös
type: "knx2knx"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "14.056"
knxDest: <ENTER YOUR KNX ADDRESS HERE>
function: "sub(<ENTER YOUR KNX ADDRESS HERE>), max(0)"
- name: "AZ Paneel on/off status"
type: "knx2knx"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.002"
knxDest: <ENTER YOUR KNX ADDRESS HERE>
#######################################################################
# Entrance Movement Detection #
# Allows mutiple devices to define turn on/turn off cycle of lights #
#######################################################################
- name: "Average Switch Entrance 3m"
type: "knx2knx"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.001"
knxDest: <ENTER YOUR KNX ADDRESS HERE>
# queueing function - allows tracing value over a period of time
function: "avMax('EntranceMovement', 18)"
- name: "Average Movement Detector Entrance 3m"
type: "knx2knx"
knxAddr: <ENTER YOUR KNX ADDRESS HERE>
knxFormat: "1.001"
knxDest: <ENTER YOUR KNX ADDRESS HERE>
# queueing function - references to the same queue
function: "avMax('EntranceMovement')"
# pooling of knx2knx value
updFreq: "very high"