KNX

KNX
Zweck / Funktion
Unterstützung des KNX Feldbus in FHEM
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE Thema
Support (Forum)	KNX/EIB
Modulname	10_KNX.pm
Ersteller	Erwin (Forum /Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Das Modul KNX implementiert die Unterstützung für den Gebäudeautomations-Feldbus KNX (eine Weiterentwicklung von EIB) innerhalb von FHEM.

Voraussetzungen

Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!

Der KNX support ist in FHEM als 2stufiges Modul konzipiert, braucht daher zusätzlich zu diesem Modul ein sog. IO-Modul, das mit der "Aussenwelt" spricht. Dzt. sind in FHEM dafür das TUL- und das KNXTUL-Modul verfügbar. Ein neues IO-Modul: KNXIO ist in Entwicklung, es wird die (meisten) Funktionen der bisherigen IO-Module unterstützen und zusätzlich weitere Kommunikationsoptionen bieten.

Weiters wird eine Schnittstellen-Hardware gebraucht zwischen dem KNX-Bus und der LAN- oder USB- oder Seriell-Schnittstelle, das kann ein serielles->KNX-Bus Modul sein (Bsp: siehe Fa. Busware TUL,...) oder auch ein Hardware Gateway oder Router.

Als Middleware kommt meistens knxd zum Einsatz. knxd wiki

Anwendung

Define

define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]

Wie in FHEM üblich, alles was hier zwischen <...> dargestellt ist, sind mandatory Angaben! Optionales wird zwischen [...] dargestellt.

Mehrfache <group><dpt>.... sind in einer Definition zulässig. Damit kann man Geräte mit komplexen Funktionen in einem FHEM Gerät abbilden. (siehe Beispiele)

Definitions-Felder im Detail

• group - Das ist die GruppenAdresse (GA) des jeweiligen KNX-Geräts. Diese wird (meist) mit der ETS in das KNX-Gerät programmiert. Ein KNX Aktor reagiert nur auf diese Adresse, wenn es eine seiner eigenen ist. Format: <0-31>/<0-7>/<0-255>
• dpt - Das ist die Definition (Data Point Type), wie FHEM und auch das KNX-Gerät den gesendeten/empfangenen Wert interpretieren! Die Werte (am Bus) können 1bit, 2bit,....4byte lang sein, oder auch 14Char.Text, oder Zeit und Datum. Falls der dpt in FHEM nicht mit dem im KNX-Gerät übereinstimmt, gibts falsche od. gar keine Werte! Eine vollständige Liste der unterstützen dpt-Types: commandref/KNX-dpt.

• gadName - GruppenAdressName bzw. GA-Alias. Angabe ist optional, sinnvoll ist ein "sprechender Name", z.B. "EinAus" od. "steuern" für eine GA die zum senden eines Befehls dient, oder z.B. "status" für die Rückmeldung vom Gerät. Ist kein gadName definiert, wird g1...g9 als gadName verwendet. Der gadName beeinflusst auch die entsprechenden Reading-Namen! Die Wahl eines gadName ist fast völlig frei - (Einschränkungen sind in der cmdref dokumentiert), allerdings ist eine Überlegung, den gadNamen so zu wählen, das der daraus abgeleitete readingName und auch set-cmd mit einem externen System (z.B. Sprachsteuerung) kompatibel ist. Z.B.: für Soll-Temperatur->desired-temp, Luftfeuchte->humidity, Luftdruck->pressure, Temperatur->temperature, usw... Damit erspart man sich mühsame mappings bei der Umsetzung der Sprachsteuerung. Beispiel: "Axxx wie ist die Solltemperatur im Wohnzimmer" - wird mit get Wohnzimmer desired-temperature übersetzt....
• set | get | listenonly - alternative optionen, optional, (nur eine Angabe möglich) zur Beeinflussung was FHEM (oder der User) mit dieser Definition machen darf. set bzw get steht für: Fhem darf senden bzw. aktiv ein Gerät abfragen, listenonly bedeutet dass weder was gesendet noch was abgefragt werden darf, es soll nur ankommende Messages verarbeitet werden. Sinnvoll z.B. bei einem Windsensor der in Intervallen die Windgeschwindigkeit auf den Bus sendet.
• nosuffix - optional, beeinflusst den readingNamen. Ohne diesen Parameter lauten Reading-Namen z.b. "EinAus-set" u. "EinAus-get" bzw. "setG1" u. "getG1", mit nosuffix fällt das -set bzw. -get weg, alle gesendeten- und empfangenen-Messages landen im reading EinAus.

Siehe commandref/KNX.

Define mittels autocreate

Autocreate wird unterstützt. Ankommende Messages erhalten DeviceNamen nach dem Schema: KNX_nnmmooo. "nn" bezeichnet die Hauptlinie, "mm" die Bereichsline und "ooo" das KNX-Gerät (= die GA_Addresse). Allerdings wird automatisch das disable Attribut gesetzt, weil autocreate keinen dpt vergeben kann und damit en- / de-coding von Messages nicht möglich ist. Es wird auch keine FileLog- oder SVG-Definition erstellt. Um das disable attribut zu löschen, muß man vorher einen gültigen dpt in die Definition einfügen. Sinnvollerweise ändert man auch den DeviceName auf etwas "sprechendes" (z.B. Licht_Wohnzimmer). Man kann das definieren durch autocreate beeinflussen, mit dem Attributen: autocreateThreshold und ignoreTypes im globalen autocreate-device.

Falls man einen FileLog für ALLE KNX-Geräte haben will, die mittels Autocreate angelegt wurden - oder künftig werden, könnte das so aussehen:

define KNX_default_Fl FileLog %L/KNX_default-%Y-W%W.log KNX_.*
attr KNX_default_Fl logtype text
attr KNX_default_Fl nrarchive 2

Attribute

Zusätzlich zu den FHEM-standard Attributen sind folgende Attribute verfügbar:

• disable - ident zum FHEM Standard - kein Senden oder Empfangen möglich!
• format - hängt den Inhalt dieses Attr. an den Wert an, - im state Reading! Sinnvoll um z.B. Einheiten hinzuzufügen.
• stateRegex - beeinflusst welcher Wert in das Reading state gesetzt wird, und zwar durch string-substitution. Siehe auch Beispiele.
• stateCmd - beeinflusst welcher Wert in das Reading state gesetzt wird, mittels perl-funktion. Siehe auch Beispiele.
• answerReading - Falls dieses Attr gesetzt ist wird auf einen read-request vom KNX Gerät mit dem Wert von state, oder falls es ein Reading <putName> gibt - mit dessen Wert, geantwortet.
• putCmd - Eine flexiblere Variante von answerReading. Hier kann mittels einer perl Funktion der Rückgabe-Wert bestimmt werden.
• KNX_toggle - Bei einem "toggle-cmd" muss das Device den aktuellen Status des Gerätes wissen. Mit diesem Attr. kann das "Status Device" definiert werden.
• IODev - Auf Grund von Änderungen im IO-Handling durch FHEM (-core) ist dieses Attribut in den allermeisten Fällen nicht mehr nötig und evtl. sogar kontraproduktiv! Die Ausnahme ist: Falls mehrere KNX-IO (TUL,KNXTUL,KNXIO) devices definiert sind. Hier ist jedoch extreme Vorsicht geboten, es kann zu endlosen msg-loops kommen!

Siehe commandref/KNX-attr.

Set Command

Ein Set command ist nur erlaubt, wenn die option im define nicht get oder listenonly ist!

Die Syntax:

set <device> <gadName> <wert> 
set <device> <wert>
set <device> g1 <wert>

In der 2ten Zeile fehlt der gadName, das ist dennoch ein gültiges Set, es wird die erste Gruppenadresse (g1) zum senden verwendet.

In der 3ten Zeile wird explizit die erste Gruppenadresse verwendet, allerdings darf dann kein gadName definiert sein!

Welche Werte sind im Set Command erlaubt ?

Die erlaubten Werte sind vom dpt abhängig!

• Alle Werte / Wertbereiche die für diesen dpt vorgesehen sind - Referenz: commandref/KNX-dpt
• Für dpt1 und dpt1.001 zusätzlich: toggle, blink <Anzahl> <Dauer>, (on|off)-for-timer <Sekunden>, (on|off)-until <hh:mm:ss>
• Für dpt10, dpt11, dpt19 (Datum/Zeit) zusätzlich: now
• Für dpt16 (14 Char Text) zusätzlich: >CLR< -löscht gesamten Text

Get Command

Ein Get command ist nur erlaubt, wenn die option im define nicht set oder listenonly ist! Die Syntax ist analog zum Set command (ohne <wert>). Kommt eine Antwort vom KNX-Gerät wird dieser Wert im entsprechenden Reading gespeichert.

Anwendungsbeispiele

Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite KNX Device Definition - Beispiele zusammengestellt.