FHEMWiki - Benutzerbeiträge [de]

KNXIO

2026-02-28T07:23:41Z

Erwin111: /* Definitions-Beispiele */ Korrektur knxd options

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.

Serielle- bzw. USB-KNX Gateways sind nicht direkt unterstützt. Empfohlen wird die Lösung mittels knxd<->KNX-Gateway und Verbindung knxd<->FHEM mittels mode KNXIO-M oder -T.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -B single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>Serielle Gateways (USB Stick / TPUART) werden vom KNXIO-Modul nicht direkt unterstützt. Für diese Varianten ist die Empfehlung, das via knxd-Daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden. (Der knxd-Daemon braucht weniger Resourcen und bietet eine wesentlich bessere Fehlertoleranz - für serielle Scnittstellen).

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Der Vorteil: Es kann keine msg verloren gehen, ohne einen Eintrag im Logfile! Falls allerdings FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest message out of sequence received: seqcntrRx received/expected= xxx/yyy - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht zur Lösung führt, ist die Empfehlung, die Kommunikation über knxd zu lösen. Also: KNX-GW <-> knxd <-> FHEM (mode S, M od. T). Der knxd als eigenständiger Deamon ist nicht von Verzögerungen durch FHEM betroffen und hat bessere Fehler-Toleranz.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

Falls KNXD Serielle oder USB Schnittstellen verwenden soll, muss im run cmd die device option verwendet werden, z.B:<syntaxhighlight lang="bash">
sudo docker run ... --device=/dev/ttyUSB0 ...
</syntaxhighlight>Alternativ kann der Container auch im privileged mode laufen, damit ist Zugriff auf '''alle''' Host devices gegeben!

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2026-01-15T13:44:43Z

Erwin111: /* Vorwort */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.

Serielle- bzw. USB-KNX Gateways sind nicht direkt unterstützt. Empfohlen wird die Lösung mittels knxd<->KNX-Gateway und Verbindung knxd<->FHEM mittels mode KNXIO-M oder -T.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>Serielle Gateways (USB Stick / TPUART) werden vom KNXIO-Modul nicht direkt unterstützt. Für diese Varianten ist die Empfehlung, das via knxd-Daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden. (Der knxd-Daemon braucht weniger Resourcen und bietet eine wesentlich bessere Fehlertoleranz - für serielle Scnittstellen).

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Der Vorteil: Es kann keine msg verloren gehen, ohne einen Eintrag im Logfile! Falls allerdings FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest message out of sequence received: seqcntrRx received/expected= xxx/yyy - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht zur Lösung führt, ist die Empfehlung, die Kommunikation über knxd zu lösen. Also: KNX-GW <-> knxd <-> FHEM (mode S, M od. T). Der knxd als eigenständiger Deamon ist nicht von Verzögerungen durch FHEM betroffen und hat bessere Fehler-Toleranz.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

Falls KNXD Serielle oder USB Schnittstellen verwenden soll, muss im run cmd die device option verwendet werden, z.B:<syntaxhighlight lang="bash">
sudo docker run ... --device=/dev/ttyUSB0 ...
</syntaxhighlight>Alternativ kann der Container auch im privileged mode laufen, damit ist Zugriff auf '''alle''' Host devices gegeben!

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2026-01-03T18:22:35Z

Erwin111: /* RaumThermostat / HeizungsAktor mit widget controlminidash */ update Beispiel

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test_Thermostat.png|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget und support siehe: {{Link2Forum|LinkText=FHEM-Forum|Topic=142831}} .
 Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt. Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
 Die KNX spezifischen Anpassungen:
 '''eventmap''' modifiziert ein "set test_Thermostat plus/minus <y>" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp <xx>", wobei xx der aktuelle wert plus/minus y ist. Der Stepwert <y> wird durch die button-definition im widgetoverride definiert. Die "fw=>...." Definition zeigt die Optionen, wie (im Detail-View) der set-cmd pulldown dargestellt oder nicht dargestellt wird. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

'''readingNmap''' alle Werte die auf GAD desired-temp-ext ankommen, werden auf reading '''desired-temp''' dargestellt. 
'''userattr knobColor knobMinMax''' ermöglicht das setzen dieser Attribute im Device. 
'''widgetOverride Parameter:''' Detaillierte Übersicht über die Parameter ist: [[FHEMWEB/ControlMiniDash#Parameterübersicht]] zu finden.

Der erste Param (ring1Val) spezifiziert einen reading-Namen, dessen wert im Ring/Knob dargestellt wird. (in diesem Beisoiel desired-temp).

Der zweite Param (ring2Val) definiert den command, der nach "mouse-out" an FHEM gesendet wird. (in diesem Beispiel: "set <device> desired-temp <value>".

Die nächsten 4 Parameter definieren reading-Namen, die Werte werden im Zentrum des Kreises dargestellt.

Die nächsten 6 Param <Icon>@<cmd> definieren Buttons links und rechts vom Kreissegment. Diese lösen commands in fhem aus. (In diesem Beispiel "Minus 1 / Plus 1" - das wird jedoch durch die eventMap in "set <device> desired-temp <aktuelle desired-temp +/- 1>" umgesetzt.
<syntaxhighlight lang="text">
defmod test_Thermostat KNX 4/0/1:dpt9:desired-temp:set:nosuffix
4/1/1:dpt9:temperature:get:nosuffix
4/2/1:dpt9:desired-temp-ext:listenonly:nosuffix
4/3/1:dpt5.001:valvepos:get:nosuffix
4/4/1:dpt5.001:humidity:get:nosuffix
attr test_Thermostat userattr knobColor knobMinMax
attr test_Thermostat comment GAs: SollTemp-schreiben, IstTemp, SollTemp-lesen, ValvePosition
attr test_Thermostat eventMap {usr=>{'^plus.(\d+)' => '" . sprintf("desired-temp %.1f",minNum(100,ReadingsNum($NAME,"desired-temp",0) + $1)) . "',
'^minus.(\d+)' => '" . sprintf("desired-temp %.1f",maxNum(0,ReadingsNum($NAME,"desired-temp",0) - $1)) . "'},
fw=> {'^plus.(\d+)' => 'plus:1,2,3,4,5', '^minus.(\d+)' => ' '}
}
attr test_Thermostat knobMinMax 5,30
attr test_Thermostat readingNmap desired-temp-ext:desired-temp
attr test_Thermostat stateCmd {return ReadingsNum($name,'temperature',0);}
attr test_Thermostat webCmd climacontrol
attr test_Thermostat widgetOverride climacontrol:controlminidash,desired-temp,desired-temp,temperature@°C,desired-temp@°C,humidity@%,valvepos,#,rc_MINUS@minus.1,#,#,rc_PLUS@plus.1,#

</syntaxhighlight>

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "Raw Definition" oder "Copy for forum..." erstellt. Erkennbar ist das an doppelten Strichpunkten und an backslash "\" am Zeilenende. Die Übernahme mit c&p in die FHEM- Kommandozeile, oder auch via Telnet funktioniert damit. Bei der Eingabe via FHEMWEB (detailView Definition, Attribut) müssen doppelte Strichpunkte und Backslash entfernt werden.

Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2025-12-29T08:17:58Z

Erwin111: /* RaumThermostat / HeizungsAktor mit widget controlminidash */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test_Thermostat.png|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget und support siehe: {{Link2Forum|LinkText=FHEM-Forum|Topic=142831}} .
 Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt. Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
 Die KNX spezifischen Anpassungen:
 '''eventmap''' modifiziert ein "set test_Thermostat plus/minus <y>" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp <xx>", wobei xx der aktuelle wert plus/minus y ist. Der Stepwert <y> wird durch die button-definition im widgetoverride definiert. Die "fw=>...." Definition zeigt die Optionen, wie (im Detail-View) der set-cmd pulldown dargestellt oder nicht dargestellt wird. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

'''readingNmap''' alle Werte die auf GAD desired-temp-ext ankommen, werden auf reading '''desired-temp''' dargestellt. 
'''userattr knobColor knobMinMax''' ermöglicht das setzen dieser Attribute im Device. 
'''widgetOverride Parameter:''' to be done - Das widget mit dieser Funktionalität ist noch nicht im SVN (im contrib), daher kann sich noch einiges an Parameter/Funktion ändern.
<syntaxhighlight lang="text">
defmod test_Thermostat KNX 4/0/1:dpt9:desired-temp:set:nosuffix
4/1/1:dpt9:temperature:get:nosuffix
4/2/1:dpt9:desired-temp-ext:listenonly:nosuffix
4/3/1:dpt5.001:valvepos:get:nosuffix
4/4/1:dpt5.001:humidity:get:nosuffix
attr test_Thermostat userattr knobColor knobMinMax
attr test_Thermostat comment GAs: SollTemp-schreiben, IstTemp, SollTemp-lesen, ValvePosition
attr test_Thermostat eventMap {usr=>{'^plus.(\d+)' => '" . sprintf("desired-temp %.1f",minNum(100,ReadingsNum($NAME,"desired-temp",0) + $1)) . "',
'^minus.(\d+)' => '" . sprintf("desired-temp %.1f",maxNum(0,ReadingsNum($NAME,"desired-temp",0) - $1)) . "'},
fw=> {'^plus.(\d+)' => 'plus:1,2,3,4,5', '^minus.(\d+)' => ' '}
}
attr test_Thermostat knobMinMax 5,30
attr test_Thermostat readingNmap desired-temp-ext:desired-temp
attr test_Thermostat stateCmd {return ReadingsNum($name,'temperature',0);}
attr test_Thermostat webCmd climacontrol
attr test_Thermostat widgetOverride climacontrol:controlminidash,desired-temp,desired-temp,temperature@°C,desired-temp@°C,humidity@%,valvepos,#,rc_MINUS@minus.1,#,#,rc_PLUS@plus.1,#

</syntaxhighlight>

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "Raw Definition" oder "Copy for forum..." erstellt. Erkennbar ist das an doppelten Strichpunkten und an backslash "\" am Zeilenende. Die Übernahme mit c&p in die FHEM- Kommandozeile, oder auch via Telnet funktioniert damit. Bei der Eingabe via FHEMWEB (detailView Definition, Attribut) müssen doppelte Strichpunkte und Backslash entfernt werden.

Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2025-12-27T23:25:42Z

Erwin111: /* Übernehmen dieser Beispiele in die eigene Konfiguration */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test_Thermostat.png|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget und support siehe: [https://forum.fhem.de/index.php?topic=142831 KNX-Forum].
 Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt. Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
 Die KNX spezifischen Anpassungen:
 '''eventmap''' modifiziert ein "set test_Thermostat plus/minus" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp xx", wobei xx der aktuelle wert plus/minus 1 ist. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

'''readingNmap''' alle Werte die auf GAD desired-temp-ext ankommen, werden auf reading '''desired-temp''' dargestellt. 
'''userattr knobColor knobMinMax''' ermöglicht das setzen dieser Attribute im Device. 
'''widgetOverride Parameter:''' to be done - Das widget mit dieser Funktionalität ist noch nicht im SVN (im contrib), daher kann sich noch einiges an Parameter/Funktion ändern.
<syntaxhighlight lang="text">
defmod test_Thermostat KNX 4/0/1:dpt9:desired-temp:set:nosuffix
4/1/1:dpt9:temperature:get:nosuffix
4/2/1:dpt9:desired-temp-ext:listenonly:nosuffix
4/3/1:dpt5.001:valvepos:get:nosuffix
4/4/1:dpt5.001:humidity:get:nosuffix
attr test_Thermostat userattr knobColor knobMinMax
attr test_Thermostat comment GAs: SollTemp-schreiben, IstTemp, SollTemp-lesen, ValvePosition
attr test_Thermostat eventMap {usr=>{'^plus' => '" . sprintf("desired-temp %.1f",minNum(100,ReadingsNum($NAME,"desired-temp",0) + 1)) . "',
'^minus' => '" . sprintf("desired-temp %.1f",maxNum(0,ReadingsNum($NAME,"desired-temp",0) - 1)) . "'},
fw=> {'^plus' => ' ', '^minus' => ' '}
}
attr test_Thermostat knobColor red
attr test_Thermostat knobMinMax 10,30
attr test_Thermostat readingNmap desired-temp-ext:desired-temp
attr test_Thermostat stateCmd {return ReadingsNum($name,'temperature',0);}
attr test_Thermostat webCmd climacontrol
attr test_Thermostat widgetOverride climacontrol:controlminidash,desired-temp,desired-temp,temperature@°C,desired-temp@°C,humidity@%,valvepos,#,rc_MINUS@minus,#,#,rc_PLUS@plus,#

</syntaxhighlight>

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "Raw Definition" oder "Copy for forum..." erstellt. Erkennbar ist das an doppelten Strichpunkten und an backslash "\" am Zeilenende. Die Übernahme mit c&p in die FHEM- Kommandozeile, oder auch via Telnet funktioniert damit. Bei der Eingabe via FHEMWEB (detailView Definition, Attribut) müssen doppelte Strichpunkte und Backslash entfernt werden.

Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2025-12-27T17:04:37Z

Erwin111: /* RaumThermostat / HeizungsAktor mit widget controlminidash */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test_Thermostat.png|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget und support siehe: [https://forum.fhem.de/index.php?topic=142831 KNX-Forum].
 Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt. Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
 Die KNX spezifischen Anpassungen:
 '''eventmap''' modifiziert ein "set test_Thermostat plus/minus" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp xx", wobei xx der aktuelle wert plus/minus 1 ist. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

'''readingNmap''' alle Werte die auf GAD desired-temp-ext ankommen, werden auf reading '''desired-temp''' dargestellt. 
'''userattr knobColor knobMinMax''' ermöglicht das setzen dieser Attribute im Device. 
'''widgetOverride Parameter:''' to be done - Das widget mit dieser Funktionalität ist noch nicht im SVN (im contrib), daher kann sich noch einiges an Parameter/Funktion ändern.
<syntaxhighlight lang="text">
defmod test_Thermostat KNX 4/0/1:dpt9:desired-temp:set:nosuffix
4/1/1:dpt9:temperature:get:nosuffix
4/2/1:dpt9:desired-temp-ext:listenonly:nosuffix
4/3/1:dpt5.001:valvepos:get:nosuffix
4/4/1:dpt5.001:humidity:get:nosuffix
attr test_Thermostat userattr knobColor knobMinMax
attr test_Thermostat comment GAs: SollTemp-schreiben, IstTemp, SollTemp-lesen, ValvePosition
attr test_Thermostat eventMap {usr=>{'^plus' => '" . sprintf("desired-temp %.1f",minNum(100,ReadingsNum($NAME,"desired-temp",0) + 1)) . "',
'^minus' => '" . sprintf("desired-temp %.1f",maxNum(0,ReadingsNum($NAME,"desired-temp",0) - 1)) . "'},
fw=> {'^plus' => ' ', '^minus' => ' '}
}
attr test_Thermostat knobColor red
attr test_Thermostat knobMinMax 10,30
attr test_Thermostat readingNmap desired-temp-ext:desired-temp
attr test_Thermostat stateCmd {return ReadingsNum($name,'temperature',0);}
attr test_Thermostat webCmd climacontrol
attr test_Thermostat widgetOverride climacontrol:controlminidash,desired-temp,desired-temp,temperature@°C,desired-temp@°C,humidity@%,valvepos,#,rc_MINUS@minus,#,#,rc_PLUS@plus,#

</syntaxhighlight>

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2025-12-27T16:49:12Z

Erwin111: /* RaumThermostat / HeizungsAktor mit widget controlminidash */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test_Thermostat.png|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget siehe: [https://forum.fhem.de/index.php?topic=142831 KNX-Forum].
 Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt. Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
 Die KNX spezifischen Anpassungen:
 '''eventmap''' modifiziert ein "set test_Thermostat plus/minus" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp xx", wobei xx der aktuelle wert plus/minus 1 ist. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

'''readingNmap alle Werte die auf GAD desired-temp-ext kommen, werden auf reading desirde-temp dargestellt.'''<syntaxhighlight lang="text">
defmod test_Thermostat KNX 4/0/1:dpt9:desired-temp:set:nosuffix
4/1/1:dpt9:temperature:get:nosuffix
4/2/1:dpt9:desired-temp-ext:listenonly:nosuffix
4/3/1:dpt5.001:valvepos:get:nosuffix
4/4/1:dpt5.001:humidity:get:nosuffix
attr test_Thermostat userattr knobColor knobMinMax
attr test_Thermostat comment GAs: SollTemp-schreiben, IstTemp, SollTemp-lesen, ValvePosition
attr test_Thermostat eventMap {usr=>{'^plus' => '" . sprintf("desired-temp %.1f",minNum(100,ReadingsNum($NAME,"desired-temp",0) + 10)) . "',
'^minus' => '" . sprintf("desired-temp %.1f",maxNum(0,ReadingsNum($NAME,"desired-temp",0) - 10)) . "'},
fw=> {'^plus' => ' ', '^minus' => ' '}
}
attr test_Thermostat knobColor red
attr test_Thermostat knobMinMax -10,30
attr test_Thermostat readingNmap desired-temp-ext:desired-temp
attr test_Thermostat stateCmd {return ReadingsNum($name,'temperature',0);;}
attr test_Thermostat webCmd climacontrol
attr test_Thermostat widgetOverride climacontrol:controlminidash,desired-temp,desired-temp,temperature@°C,desired-temp@°C,humidity@%,valvepos,#,rc_MINUS@minus,#,#,rc_PLUS@plus,#

</syntaxhighlight>

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2025-12-27T16:37:42Z

Erwin111: /* RaumThermostat / HeizungsAktor mit widget controlminidash */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test_Thermostat.png|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget siehe: [https://forum.fhem.de/index.php?topic=142831 KNX-Forum].
 Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
 Die KNX spezifischen Anpassungen:
 '''eventmap''' modifiziert ein "set test_Thermostat plus/minus" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp xx", wobei xx der aktuelle wert plus/minus 1 ist. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

Datei:Test Thermostat.png

2025-12-27T16:29:46Z

Erwin111:

KNX Device Definition - Beispiele

2025-12-27T16:20:08Z

Erwin111: /* RaumThermostat / HeizungsAktor mit widget */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== RaumThermostat / HeizungsAktor mit widget controlminidash ====
[[Datei:Test Thermostat|rahmenlos|rechts|alternativtext=screenshot]]
Ähnlich dem obigen Beispiel, die GUI jedoch mit dem widget '''controlminidash''' gestaltet. Details zu diesem widget siehe: [https://forum.fhem.de/index.php?topic=142831 KNX-Forum].
Das widget besteht aus einem Kreissegment, um den aktuellen Wert anzeigen und ändern zu können. Im Zentrum werden bis zu 4 Werte dargestellt Zusätzlich sind bis zu 6 Buttons möglich. Wertbereich und Farbe des Sliders sind durch user-Attribute definierbar.
Die KNX spezifischen Anpassungen:
'''eventmap''' modifiziert ein "set test_Thermostat plus/minus" event (ausgelöst durch die beiden buttons plus/minus) zu "set test_Thermostat desired-temp xx", wobei xx der aktuelle wert plus/minus 1 ist. Die syntax ist gewöhnungsbedürftig, aber sie funktioniert.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX

2025-12-09T12:18:16Z

Erwin111: /* Define mittels autocreate */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst hier: https://wiki.fhem.de/wiki/KNX#Umstellung_von_EIB_auf_KNX_Modul oder diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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). Als dpt-Typ wird dptRAW gesetzt, weil autocreate keinen richtigen dpt vergeben kann . Wichtig ist, einen korrekten dpt-Typ zu definieren, damit valides en- / de-coding von Messages möglich ist. Es wird auch keine FileLog- oder SVG-Definition erstellt. 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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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! Diese Attribut ist abgekündigt, nicht mehr verwenden. Besser stateCmd, stateRegex oder stateFormat verwenden.
* '''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.
* '''putCmd''' - Falls dieses Attr gesetzt ist, wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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.
* '''readingNmap''' - ändert reading Name(n) mittels regex. Beispiele in der cmd-ref. Dieses Attribut wird vor allen anderen Attributen verarbeitet, daher müssen readingNamen die in z.B. stateCmd,..., notifies... verwendet werden, angepasst 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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung von EIB auf KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr aktualisiert wurde und abgekündigt ist, möchte ich dazu motivieren, auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen und Beispiele sind in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNXIO

2025-12-08T09:43:06Z

Erwin111: /* Bekannte Probleme */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>Serielle Gateways (USB Stick / TPUART) werden vom KNXIO-Modul nicht direkt unterstützt. Für diese Varianten ist die Empfehlung, das via knxd-Daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden. (Der knxd-Daemon braucht weniger Resourcen und bietet eine wesentlich bessere Fehlertoleranz - für serielle Scnittstellen).

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Der Vorteil: Es kann keine msg verloren gehen, ohne einen Eintrag im Logfile! Falls allerdings FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest message out of sequence received: seqcntrRx received/expected= xxx/yyy - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht zur Lösung führt, ist die Empfehlung, die Kommunikation über knxd zu lösen. Also: KNX-GW <-> knxd <-> FHEM (mode S, M od. T). Der knxd als eigenständiger Deamon ist nicht von Verzögerungen durch FHEM betroffen und hat bessere Fehler-Toleranz.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

Falls KNXD Serielle oder USB Schnittstellen verwenden soll, muss im run cmd die device option verwendet werden, z.B:<syntaxhighlight lang="bash">
sudo docker run ... --device=/dev/ttyUSB0 ...
</syntaxhighlight>Alternativ kann der Container auch im privileged mode laufen, damit ist Zugriff auf '''alle''' Host devices gegeben!

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2025-12-07T14:52:39Z

Erwin111: /* Timing Problem Mode H */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>Serielle Gateways (USB Stick / TPUART) werden vom KNXIO-Modul nicht direkt unterstützt. Für diese Varianten ist die Empfehlung, das via knxd-Daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden. (Der knxd-Daemon braucht weniger Resourcen und bietet eine wesentlich bessere Fehlertoleranz - für serielle Scnittstellen).

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht zur Lösung führt, ist die Empfehlung, die Kommunikation über knxd zu lösen. Also: KNX-GW <-> knxd <-> FHEM (mode S, M od. T). Der knxd als eigenständiger Deamon ist nicht von Verzögerungen durch FHEM betroffen und hat bessere Fehler-Toleranz.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

Falls KNXD Serielle oder USB Schnittstellen verwenden soll, muss im run cmd die device option verwendet werden, z.B:<syntaxhighlight lang="bash">
sudo docker run ... --device=/dev/ttyUSB0 ...
</syntaxhighlight>Alternativ kann der Container auch im privileged mode laufen, damit ist Zugriff auf '''alle''' Host devices gegeben!

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNX

2025-12-07T11:46:29Z

Erwin111: /* Attribute */ readingNmap neu

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst hier: https://wiki.fhem.de/wiki/KNX#Umstellung_von_EIB_auf_KNX_Modul oder diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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! Diese Attribut ist abgekündigt, nicht mehr verwenden. Besser stateCmd, stateRegex oder stateFormat verwenden.
* '''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.
* '''putCmd''' - Falls dieses Attr gesetzt ist wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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.
* '''readingNmap''' - ändert reading Name(n) mittes regex. Beispiele in der cmd-ref. Diese Attribut wird vor allen anderen Attributen verarbeitet, daher müssen readingNamen die in z.B. stateCmd,..., notifies... verwendet werden, angepasst 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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung von EIB auf KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr aktualisiert wurde und abgekündigt ist, möchte ich dazu motivieren, auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen und Beispiele sind in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNX

2025-12-07T11:38:38Z

Erwin111: /* Attribute */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst hier: https://wiki.fhem.de/wiki/KNX#Umstellung_von_EIB_auf_KNX_Modul oder diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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! Diese Attribut ist abgekündigt, nicht mehr verwenden. Besser stateCmd, stateRegex oder stateFormat verwenden.
* '''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.
* '''putCmd''' - Falls dieses Attr gesetzt ist wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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.
* '''readingNmap''' - blblabla
* '''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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung von EIB auf KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr aktualisiert wurde und abgekündigt ist, möchte ich dazu motivieren, auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen und Beispiele sind in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2024-11-10T17:49:37Z

Erwin111: /* on/off Device - mit verzögerter Rückmeldung */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:switch:set 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /switch-set/steuern-/ /switch-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:switch:set:nosuffix 14/2/1:dpt1:status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off off:off:on
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name switch off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # sende text zum KNX display (max 14 Char.)
set textdev txt >CLR< # löscht gesamten text am KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon. Das Beispiel soll auch zeigen, dass man aus einem cmd bzw. event einen (zusätzlichen) beliebigen reading-namen mit Wert erstellen kann.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2024-11-04T14:32:10Z

Erwin111: /* Garagentor Steuerung */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:EinAus:set:nosuffix 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'Status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name EinAus off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "Status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-move ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-move_status ist die übliche Rückmeldung vom Status des Aktors. Wird hier nicht verwendet, kann weggelassen werden.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:move:set:nosuffix\
14/1/101:dpt1.001:move_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 2 seconds, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'move on-for-timer 2','move off'=>'off'} }
attr Garagentor stateRegex /move// /move_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride move:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set move on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von move und von move_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
#attr Slider2_Test userReadings Position:PosStatus.* {return readingsNum($name, 'PosStatus',0);; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt.

Alternativ zu Attr stateCmd kann auch Attr userReadings verwendet werden.

Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-10-30T10:15:26Z

Erwin111: /* KNXD im Docker & Multicast */ --device option

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>Serielle Gateways (USB Stick / TPUART) werden vom KNXIO-Modul nicht direkt unterstützt. Für diese Varianten ist die Empfehlung, das via knxd-Daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden. (Der knxd-Daemon braucht weniger Resourcen und bietet eine wesentlich bessere Fehlertoleranz - für serielle Scnittstellen).

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

Falls KNXD Serielle oder USB Schnittstellen verwenden soll, muss im run cmd die device option verwendet werden, z.B:<syntaxhighlight lang="bash">
sudo docker run ... --device=/dev/ttyUSB0 ...
</syntaxhighlight>Alternativ kann der Container auch im privileged mode laufen, damit ist Zugriff auf '''alle''' Host devices gegeben!

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNX

2024-07-29T10:56:41Z

Erwin111: /* Umstellung EIB -> KNX Modul */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst hier: https://wiki.fhem.de/wiki/KNX#Umstellung_von_EIB_auf_KNX_Modul oder diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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.
* '''putCmd''' - Falls dieses Attr gesetzt ist wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung von EIB auf KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr aktualisiert wurde und abgekündigt ist, möchte ich dazu motivieren, auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen und Beispiele sind in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNX

2024-07-29T10:56:10Z

Erwin111: /* Anwendung */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst hier: https://wiki.fhem.de/wiki/KNX#Umstellung_von_EIB_auf_KNX_Modul oder diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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.
* '''putCmd''' - Falls dieses Attr gesetzt ist wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung EIB -> KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr aktualisiert wurde und abgekündigt ist, möchte ich dazu motivieren, auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen und Beispiele sind in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNX

2024-07-29T10:51:29Z

Erwin111: /* Anwendung */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst hier: https://wiki.fhem.de/wiki/KNX#Umstellung_EIB_->_KNX_Modul oder diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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.
* '''putCmd''' - Falls dieses Attr gesetzt ist wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung EIB -> KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr aktualisiert wurde und abgekündigt ist, möchte ich dazu motivieren, auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen und Beispiele sind in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNXIO

2024-07-16T16:07:47Z

Erwin111: /* TUL-Modul */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>Serielle Gateways (USB Stick / TPUART) werden vom KNXIO-Modul nicht direkt unterstützt. Für diese Varianten ist die Empfehlung, das via knxd-Daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden. (Der knxd-Daemon braucht weniger Resourcen und bietet eine wesentlich bessere Fehlertoleranz - für serielle Scnittstellen).

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-07-16T15:53:00Z

Erwin111: /* Umstellung von TUL oder KNXTUL Modul */ Beschreibung vereinfacht

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: fhem.cfg sichern! Bestehende TUL/KNXTUL - Definition noch nicht löschen, neue KNXIO - Definition anlegen.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht. Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das löschen vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Danach save - FHEM restart! Den fhem-start mit einem Blick ins Log-file beobachten.

Danach die bisherige TUL/KNXTUL definition löschen.

Es sollte jetzt das '''Reading IODev''' in allen KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2024-06-13T14:16:11Z

Erwin111: /* RGBW Steuerung (dpt251.600) */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:EinAus:set:nosuffix 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'Status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name EinAus off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "Status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.

<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird '''[[AutoShuttersControl|hier]]''' behandelt. Im Folgenden werden nur jene Definitionen gezeigt, die KNX-spezifisch sind.

Einige Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: automatisch Rauf-/Runterfahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstation auch Beschattung. Das ASC Modul sendet Werte von 0-100, um die Jalousieposition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>
ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device übereinstimmen.

ASC_CommandTemplate: so muss der set command für das KNX-Device zusammengestellt werden, also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist, um die korrekte Funktion des ASC Moduls zu erhalten.

Um die Funktion zu testen, kann man den Befehl '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus.

Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

Knxd

2024-04-24T12:23:51Z

Erwin111: /* FAQ */

== knxd mit einem IP Gateway einrichten ==
Damit FHEM auf den KNX Bus zugreifen kann, wird ein passendes Interface benötigt. Es gibt:
* RS232
* USB
* IP

Im Folgenden wird die Einrichtung von knxd mit einem IP Gateway auf einem Raspberry Pi2 mit Wheezy oder Jessie beschrieben.

=== Installation ===

==== Für Debian Jessie: ====
'''als erstes müssen folgende Pakete installiert werden (Referenz Debian Jessie):'''
<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install debhelper cdbs automake libtool libusb-1.0-0-dev git-core build-essential libsystemd-daemon-dev dh-systemd libev-dev cmake
</syntaxhighlight>

'''knxd herunterladen und installieren'''
Achtung: Wenn Abhängigkeiten fehlen, dann müssen diese nachinstalliert werden. Nicht einfach mittels "-d" diese übergehen!
<syntaxhighlight lang="bash">
git clone https://github.com/knxd/knxd.git
cd knxd
git checkout deb
dpkg-buildpackage -b -uc
cd ..
sudo dpkg -i knxd_*.deb knxd-tools_*.deb
</syntaxhighlight>

==== Ab Debian Stretch, Buster, ... ====
'''knxd ist in den Debian packages vorhanden, muss daher nicht compiliert werden.'''
<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install knxd knxd-tools

</syntaxhighlight>

Mit der Konfiguration '''mit Systemd weitermachen!'''
=== Konfiguration ===
'''1. Ohne systemd'''

Es muss als nächstes die Konfigurationsdatei editiert werden, das geht mit:
<syntaxhighlight lang="bash">
sudo nano /etc/default/knxd
</syntaxhighlight>
dann folgende Einträge anpassen:
<syntaxhighlight lang="bash">
DAEMON_ARGS="-u /tmp/eib -u /var/run/knx -i -b ipt:192.168.188.XX"
</syntaxhighlight>
und
<syntaxhighlight lang="bash">
START_KNXD=YES
</syntaxhighlight>

'''2. Mit systemd z. B. für Debian Jessie'''

Die Konfigurationsdatei bei Jessie hat sich wegen der Nutzung von systemd geändert:
<syntaxhighlight lang="bash">
sudo nano /etc/knxd.conf
</syntaxhighlight>
dann folgende Einträge anpassen:
<syntaxhighlight lang="bash">
KNXD_OPTS="-e 1.2.202 -E 1.2.203:8 -c -DTRS -b ipt:192.168.188.XX"

</syntaxhighlight>Bei Verwendung von KNXIO als IO-Modul finden sich detaillierte infos zu diesen Parametern hier: {{Link2CmdRef|Anker=KNXIO-define}}

=== knxd Status überprüfen ===
<syntaxhighlight lang="bash">
/etc/init.d/knxd status
</syntaxhighlight>

== knxd als IP-Gateway einrichten ==
Der knxd kann auch gleich als IP-Gateway eingerichtet und sowohl mit FHEM als auch parallel mit der ETS genutzt werden. Dazu ist, neben einem Raspberry Pi, ein Interface zum KNX-Bus erforderlich. Geeignet sind z.B.:
* ROT
* PIGATOR mit PIM-TPUART
* TUL
der Fa. [http://busware.de Busware]. Wer einen Rasperry Pi3 benutzen möchte, der sollte zum TUL greifen, da die serielle Schnittstelle UART0 das Bluetooth-Modul des Pi3 bedient und wieder auf die GPIO-Pins umgeleitet werden muss. Der TUL bringt seine eigene serielle Schnittstelle mit, so dass Bluetooth erhalten bleibt.

=== Vorbereiten des TUL ===
==== TUL flashen ====
Der TUL wird ohne Software geliefert und kann über den Raspberry Pi programmiert werden:
<syntaxhighlight lang="bash">
sudo apt-get install dfu-programmer
wget -O TPUARTtransparent.hex http://busware.de/tiki-download_file.php?fileId=54
sudo dfu-programmer atmega32u4 erase
sudo dfu-programmer atmega32u4 flash TPUARTtransparent.hex
sudo dfu-programmer atmega32u4 reset
sudo reboot
</syntaxhighlight>
Soll der TUL unter Windows programmiert werden, so geht das mit [https://www.microchip.com/developmenttools/ProductDetails/FLIP FLIP]. Die HEX-Datei kann [http://files.busware.de/TUL/Transparent/ hier] herunter geladen werden.
Der TUL hat an der Unterseite einen winzigen Button. Dieser muss gedrückt werden, während der TUL in die USB-Buchse gesteckt wird.
In FLIP nun als ''Device=>Select'' ATmega32U4 auswählen und über ''Settings=>Communication=>USB'' die Verbindung herstellen. *.hex-Datei laden und im Rahmen ''Operation-Flow'' auf ''Run'' klicken. Fertig.

==== TUL einen dauerhaften Namen geben ====
Linux bindet USB-Geräte beim Boot in einer eher zufälligen Reihenfolge ein. Werden mehrere USB-Geräte betrieben, so ist es sinnvoll, dem TUL einen festen Namen zuzuordnen. Dazu wird der TUL zunächst mit dem Befehl
<syntaxhighlight lang="bash">
ls -la /dev/serial/by-id/
</syntaxhighlight>
identifiziert. Das Ergebnis sollte ungefähr so aussehen
<syntaxhighlight lang="bash">
usb-busware.de_TPUART_8543934393935171B1C1-if00 -> ../../ttyACM0
</syntaxhighlight>
Die Seriennummer (8543934393935171B1C1) wird später benötigt. Der Befehl
<syntaxhighlight lang="bash">
lsusb
</syntaxhighlight>
sollte u.a. diese Zeile liefern
<syntaxhighlight lang="bash">
Bus 001 Device 005: ID 03eb:204b Atmel Corp. LUFA USB to Serial Adapter Project
</syntaxhighlight>
03eb ist dabei die Herstellerkennung, 204b die Produktkennung. Nun muss die Datei /etc/udev/rules.d/99-usb-serial.rules
<syntaxhighlight lang="bash">
sudo nano /etc/udev/rules.d/99-usb-serial.rules
</syntaxhighlight>
erstellt oder erweitert werden mit der Zeile
<syntaxhighlight lang="bash">
SUBSYSTEM=="tty", ATTRS{idVendor}=="03eb", ATTRS{idProduct}=="204b", ATTRS{serial}=="8543934393935171B1C1", SYMLINK+="knx", OWNER="knxd"
</syntaxhighlight>
Der TUL wird dann unter /dev/knx erreichbar sein. Der knxd läuft als Benutzer knxd und hat damit die Berechtigung, auf den TUL zuzugreifen.

=== Vorbereiten des Raspberry Pi für ROT oder PIGATOR ===
Der Raspberry Pi nutzt standardmäßig die serielle Schnittstelle als Terminal. Dies muss deaktiviert werden:
<syntaxhighlight lang="bash">
sudo raspi-config
5 Interfaceoption
P6 Serial
</syntaxhighlight>
Der knxd arbeitet als Benutzer knxd. Nach der Installation von knxd muss dieser noch der Gruppe dialout zugeordnet werden, damit er auf ttyAMA0 zugreifen kann:
<syntaxhighlight lang="bash">
sudo usermod -aG dialout knxd
</syntaxhighlight>
Die Raspberry Pi 3 und 4 nutzen für die serielle Schnittstelle einen mini UART, der nicht mit dem knxd zusammenarbeitet. Der Hardware UART wird für Bluetooth verwendet. Bluetooth muss deaktiviert werden, damit der Hardware UART wieder unter ttyAMA0 zur Verfügung steht. In der /boot/config.txt muss die Zeile
<syntaxhighlight lang="bash">
dtoverlay=disable-bt
</syntaxhighlight>
am Ende eingefügt werden. Nun muss noch der Dienst hciuart deaktiviert werden (initialisiert das Bluetooth-Modem):
<syntaxhighlight lang="bash">
sudo systemctl disable hciuart
</syntaxhighlight>
Nach einem anschließenden Reboot ist der TPUART unter ttyAMA0 ansprechbar.

Nach dieser Prozedur ist natürlich die Benuzung des Bluetooth-Moduls nicht mehr möglich. Wer das Modul benötigt, findet die Anleitung hier:

[[Raspberry Pi 3: GPIO-Port Module und Bluetooth]]

Der Raspberry Pi 4 besitzt weitere UARTs, die auch für den knxd genutzt werden können. Weitere Informationen dazu gibt es [https://gitlab.com/knx-makerstuff/knx_microbcu2/-/wikis/DualKNX-RaspiHat-Quick-Installation-Guide#uart-configuration hier].

=== Andere BCU's (BusCouplerUnit) ===
Natürlich sind auch andere BCU's geeignet. Wer weiß, an welchem Ende er einen Lötkolben anzufassen hat, ist mit der [https://knx-user-forum.de/forum/projektforen/konnekting/1045398-microbcu-sehr-kleiner-knx-transceiver MicroBCU] gut bedient. Sie kann z.B. über einen ADUM1201 mit dem UART des Raspberry Pi verbunden werden (Tx->Rx, Rx->Tx, Konfiguration wie unter [[Knxd#Vorbereiten_des_Raspberry_Pi_f.C3.BCr_ROT_oder_PIGATOR|ROT]] beschrieben) oder über einen USB2Seriell-Konverter (Konfiguration ähnlich [[Knxd#TUL_einen_dauerhaften_Namen_geben|TUL]]).{{Hinweis|Die MicroBCU wird vom Bus gespeist und liefert auch zwei Spannungen, wovon die 3,3V auch für den ADUM genutzt werden kann. Wer den Raspi aus dem KNX-Netzteil versorgen möchte, sollte sich [https://knx-user-forum.de/forum/%C3%B6ffentlicher-bereich/knx-eib-forum/diy-do-it-yourself/1597469-dualknx-microbcu-hat-f%C3%BCr-raspberrypi-mit-dc-dc-netzteil das hier] mal ansehen.}}

=== Installieren des knxd ===
Die Installation erfolgt nun wie oben unter [[Knxd#Installation|Installation]] beschrieben. Hier noch mal der dringende Hinweis, fehlende Abhängigkeiten nicht mit -d zu überspringen. Jede Abhängigkeit, die als Fehlend moniert wird, nachinstallieren und Kompilierung neu starten. Prozedur notfalls mehrfach wiederholen. Das Kompilieren dauert und manchmal geht es scheinbar nicht weiter. Also Geduld.

=== Konfiguration ===
Die Konfiguration erfolgt wieder in der knxd.conf mit
<syntaxhighlight lang="bash">
sudo nano /etc/knxd.conf
</syntaxhighlight>
Nun die Konfiguarionszeile anpassen 
(serielle Schnittstelle)
<syntaxhighlight lang="bash">
KNXD_OPTS="-e 1.2.202 -E 1.2.203:8 -c -DTRS -b tpuarts:/dev/ttyAMA0"
</syntaxhighlight>
(USB)
<syntaxhighlight lang="bash">
KNXD_OPTS="-e 1.2.202 -E 1.2.203:8 -c -DTRS -b tpuarts:/dev/knx"
</syntaxhighlight>
Und dann noch
<syntaxhighlight lang="bash">
START_KNXD=YES
</syntaxhighlight>
um knxd beim Systemstart sofort zu starten.

-e definiert die physikalische Adresse des knxd, -E definiert einen Adressbereich für ETS5 etc. (hier einen Bereich aus acht Adressen). Diese Adressen müssen an das eigene Netz angepasst werden. In FHEM sieht das dann so aus
<syntaxhighlight lang="bash">
define myKNXGW KNXIO T 127.0.0.1:6720 1.2.203
</syntaxhighlight>
alternativ via Multicast: (siehe auch KNXIO-wiki):<syntaxhighlight lang="bash">
define myKNXGW KNXIO M 224.0.23.12:3671 1.2.203
</syntaxhighlight>
Spätestens jetzt sollte der KNX-Bus angeschlossen werden.{{Hinweis|Da der TPUART (wie auch andere BCU‘s) vom Bus gespeist wird, kann der knxd den TPUART nur initialisieren, wenn der Bus angeschaltet ist.}}
Wer Multicast nutzen möchte, muss ab Buster dieses noch aktivieren (z.B. für Tasmota-KNX)
<syntaxhighlight lang="bash">
sudo nano /proc/sys/net/ipv4/icmp_echo_ignore_broadcasts
"1" durch "0" ersetzen
</syntaxhighlight>
Nach einem
<syntaxhighlight lang="bash">
sudo reboot
</syntaxhighlight>
sollte der knxd dann laufen.
{{Hinweis|Manche KNX-Module bringen zusätzlich eine IP-Gateway-Funktion mit (z.B. sonnenKNX zur Verbindung der sonnenBatterie mit dem KNX-Bus). Hier führt die Option -R in der Konfigurationsdatei zu Problemen (KNX-IP Daten werden mehrfach auf den Bus gespiegelt). Daher muss die Option -R entfernt werden (-DTS), wenn ein solches Modul nachträglich in das System integriert wird.}}

== KNXD im Docker Environment ==
siehe: [[KNXIO#KNXD_im_Docker_&_Multicast]]

== FAQ ==
'''Wie wird eibd vorher deinstalliert?'''
<syntaxhighlight lang="bash">
sudo rm -r /usr/local/bin/{eibd,knxtool,group*} /usr/local/lib/lib{eib,pthsem}*.so* /usr/local/include/pth*
</syntaxhighlight>

'''Hinweis''': knxd unterstützt im Gegensatz zu eibd die Hilfsprogramme knxtools nur sehr eingeschränkt (Siehe dazu Hinweis unter https://github.com/knxd/knxd#migrating-to-012. "progmode" sowie alle mit "m" beginnenden Kommandos sind entgegen der Doku ab Version 0.12 nicht mehr funktionsfähig.

'''folgender Fehler: dpkg-buildpackage: Fehler: Fehler-Exitstatus von debian/rules build war 2'''
<syntaxhighlight lang="bash">
sudo apt-get install git-core build-essential
</syntaxhighlight>

oder

<syntaxhighlight lang="bash">
in der datei knxd/debian/rules die Zeile:
bash tools/test.sh auskommentieren
</syntaxhighlight>

'''Fehler: dpkg-buildpackage: error: fakeroot not found, either install the fakeroot <....> '''
<syntaxhighlight lang="bash">
sudo apt-get install fakeroot dpkg-dev
</syntaxhighlight>

== Links ==
* [[Benutzer:Marthinx]]
* [https://github.com/knxd/knxd Github knxd]
* [https://knx-user-forum.de/forum/projektforen/knxd/1049547-grundlagen-zum-knxd-mit-installationsanleitung-vor-dem-schreiben-lesen Forums-Thread zu knxd. Sehr informativ.]

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-04-24T12:10:19Z

Erwin111: /* Attribute */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-04-24T12:08:21Z

Erwin111: /* Attribute */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=de|Anker=KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-04-24T12:05:19Z

Erwin111: /* Definitions-Beispiele */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=de|Anker=KNXIO#KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-04-24T12:03:25Z

Erwin111: Attribute enableKNXscan added

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.
* '''enableKNXscan''' - löst ein KNXscan cmd aus: nie -> 0 , Fhem Start -> 1 , bei jedem connect event -> 2. Details dazu: {{Link2CmdRef|Lang=de|Anker=#KNX-utilities|Label=hier}}

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-04-02T10:05:24Z

Erwin111: /* KNXD im Docker & Multicast */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch '''Multicas'''t oder '''discovery''' (verwendet von ETS) unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-03-26T10:08:42Z

Erwin111: /* KNXD im Docker & Multicast */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen.

Das ''--network=mymacvlannetwork'' ist nur notwendig, falls der knxd auch Multicast unterstützen soll.

Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker Container) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>Multicast zwischen Docker-Containern (FHEM <.> knxd) funktioniert nicht, daher die Empfehlung KNXIO mode S zu verwenden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-03-26T09:28:50Z

Erwin111: /* KNXD im Docker & Multicast */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen. Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker) mittels KNXIO mode S ! Die dazu passende FHEM Definition:<syntaxhighlight lang="text">
define <name> KNXIO S UNIX:STREAM:/var/run/knx/knxd.sock <x.y.z>
</syntaxhighlight>

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-03-26T09:21:30Z

Erwin111: /* KNXD im Docker & Multicast */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen. Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker) mittels KNXIO mode S !

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-03-26T09:15:11Z

Erwin111: /* neu: KNXD im Docker & Multicast */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== FHEM im Docker Environment & Multicast ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== KNXD im Docker & Multicast ==
KNXD Docker Images gibit es einige am docker.hub, die meisten davon kompilieren knxd aus den sourcen, was nicht mehr nötig ist. Daher hier eine Anleitung, wie knxd im Docker funktionieren kann, inklusive MC-support:

Ein Verzeichnis erstellen und in dieses wechseln:, z.B:

''mkdir ~/knxd && cd ~/knxd''

'''Dockerfile in diesem Verzeichnis erstellen:'''<syntaxhighlight lang="dockerfile">
FROM debian:bullseye-slim AS knxd

ENV TZ="Europe/Vienna"
RUN date

RUN apt-get update \
&& apt-get upgrade -y \
&& apt-get install -y \
knxd \
knxd-tools \
net-tools \
iproute2 \
iputils-ping \
nano \
procps \
&& rm -rf /var/lib/apt/lists/* /var/log/* /var/tmp/* /tmp/* /usr/share/doc/* /usr/share/man/*/* /var/cache/apt \
&& adduser knxd tty

COPY --chmod=755 ./startknxd.sh /
COPY --chmod=666 ./knxd.ini /

RUN mkdir /var/run/knx
RUN chmod 777 /var/run/knx

EXPOSE 3671/udp
EXPOSE 6720

ENTRYPOINT ["/startknxd.sh"]
</syntaxhighlight>'''startknxd.sh erstellen:'''<syntaxhighlight lang="bash">
#!/bin/bash
# wait for knxd started and create socks file
#sleep 10 && chmod 777 /var/run/knx/knxd.sock &
SOCKSFILE="/var/run/knx/knxd.sock"
waitForSocksFile() {
local sFile="$1"

local dt=$(date '+%F %H:%M:%S.%3N')
echo -en "${dt} waiting for knxd start "
for i in {1..20}
do
if test -S "$sFile"; then
echo -e "\n$(date '+%F %H:%M:%S.%3N') socks file updated\n"
chmod 777 $sFile
break
else
echo -en "."
fi
sleep 0.5
done

}

if test -e "$SOCKSFILE"; then
rm "$SOCKSFILE" # delete old file
fi

waitForSocksFile "$SOCKSFILE" &
sleep 0.2
exec knxd /knxd.ini
</syntaxhighlight>'''knxd.ini erstellen:'''<syntaxhighlight lang="ini">
[A.tcp]
server = knxd_tcp
filters = retryFilter
systemd-ignore = true
[B.unix]
path = /var/run/knx/knxd.sock
server = knxd_unix
systemd-ignore = true
[C.ipt]
driver = ipt
filters = retryFilter
ip-address = 192.168.10.232
[debug-server]
name = mcast:knxd
[main]
addr = 0.0.20
client-addrs = 0.0.21:8
connections = server,A.tcp,B.unix,C.ipt
systemd = systemd
[server]
debug = debug-server
discover = true
multicast-address = 224.0.23.12
port = 3671
router = router
server = ets_router
tunnel = tunnel
[retryFilter]
filter = retry
max-retries = 0
retry-delay = 60
start-timeout = 10
may-fail = true

</syntaxhighlight>Diese knxd.ini ist als Beispiel zu sehen, muß jedenfalls an die eigenen Anfordeungen angepasst werden. Es gibt ein Utility um eine knxd.ini aus dem commandline-syntax zu erstellen:<syntaxhighlight lang="shell">
/usr/lib/knxd_args -e 0.0.20 -E 0.0.21:8 -D -T -R .... >knxd.ini
</syntaxhighlight>Wichtig: Nachdem in diesem docker-image '''kein systemd''' läuft, alle Einräge auf: ''systemd-ignore = true'' ändern! Weiters ist der Abschnitt retryFilter sinnvoll, wel sonst der knxd unmittelbar terminiert (Error: F00000105), falls ein x.ipt oder x.tcp nicht erreichbar sein sollte!

'''create image & run knxd:'''<syntaxhighlight lang="bash">
sudo docker build -t MH/knxd .
sudo docker run -d --name knxd --network=mymacvlannetwork --ip=192.168.5.145 -h cl-RPI4-knxd -v /var/run/knx:/var/run/knx --restart=unless-stopped MH/knxd
</syntaxhighlight>build muss bei jeder Änderung in knxd.ini und startknxd.sh aufgerufen werden. Name / Host-name / ImageName / ip sind als Beispiel zu sehen. Das ''-v /var/run/knx:/var/run/knx'' ermöglicht die Kommunikation via socks file zu einem FHEM (im Docker) mittels KNXIO mode S !

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-03-19T17:16:26Z

Erwin111: /* KNX im Docker Environment */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== KNX im Docker Environment ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 16 Addressen 192.168.5.144 - .159), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' (optional) eine statische Adresse aus dem definierten ip-range. Falls nicht angegeben, vergibt Docker eine Adresse aus diesem Bereich.
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar. Von anderen Containern im gleichen macvlan ist der FHEM-container unter ''fhemdocker.mymacvlannetwork'' erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-02-29T10:52:56Z

Erwin111: /* KNX im Docker Environment */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

== KNX im Docker Environment ==
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 8 Addressen 192.168.5.144 - .151), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' eine (statische) Adresse aus den definierten ip-range Bereich
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-02-29T10:51:17Z

Erwin111: /* KNX im Docker Environment */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

=== KNX im Docker Environment ===
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher Docker host-mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip-range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 8 Addressen 192.168.5.144 - .151), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' eine (statische) Adresse aus den definierten ip-range Bereich
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-02-20T18:31:47Z

Erwin111: /* KNX im Docker Environment */

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

==== KNX im Docker Environment ====
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher host mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip.range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 8 Addressen 192.168.5.144 - .151), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' eine (statische) Adresse aus den definierten ip-range Bereich
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar.

Nicht erreichbar ist vom docker host der FHEM Container und umgekehrt! Das ist eine Docker/macvlan Einschränkung. Container <-> Container connectivity ist gegeben, wenn die Container im gleichen macvlan sind.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNXIO

2024-02-20T11:03:12Z

Erwin111: neu: KNX im Docker environment

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=
|ModTechName=00_KNXIO.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNXIO]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Vorwort ==
KNX ist in FHEM nach dem 2-stufigen Modell implementiert. Das KNXIO-Modul unterstützt die Kommunikation mit einem KNX-Gateway, der "Aussenwelt", während das [[KNX|KNX-Modul]] die logische Schnitstelle zum Anwender ist.

Die Idee zu diesem Modul ist: ein Modul für (fast) alle möglichen Kommunikations-Varianten zu haben, das auch vernünftig wartbar ist. Dieses Modul soll langfristig die bisherigen Module TUL und KNXTUL ablösen.

KNX-secure ist nicht unterstüzt, weil bisher m.W. keine frei zugängliche Dokumentation des Prokotolls verfügbar ist und ich dzt. kein GW besitze, dass KNX-secure unterstützt.
== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNXIO <[MHT]> <IP-Adresse/Hostname>:<Port> <Phy-Adresse> bzw.
define <name> KNXIO S <socket-path> <Phy-Adresse>

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

==== Definitions-Felder im Detail ====
[[Datei:KNXIO.png|gerahmt|KNXIO Connectivity]]

====== Mode: ======
* '''H -Host Mode:''' Verbindung zu einem KNX-Gateway mit UDP Point-Point Protokoll. Dieser Protokoll wird auch von der ETS verwendet (KNXNET/IP). Das Protokoll ist sehr kritisch in Bezug auf Timing, Verzögerungen in FHEM (durch andere Tasks...) größer 1 Sekunde führen zu Verbindungsabbrüchen! Die Verbindung wird zwar unmittelbar wieder hergestellt, allerdings können einige Messages verloren gehen.
* '''M -Multicast mode:''' Verbindung zu knxd-Daemon oder KNX-Router mit Multicast Protokoll. Dieses Protokoll wird auch von der ETS verwendet (KNXNET/Routing). Falls ein KNX-Gateway Multicast unterstützt, braucht man keine knxd Installation! Dieser Modus ist der Nachfolger des KNXTUL-Moduls.
* '''T -TCP Mode:''' Verbindet mittels TCP-Protokoll mit knxd. Dieser Modus ist der Nachfolger des TUL-Moduls.. Eine direkte Unterstützung von Seriellen/USB Gateways ist nicht implementiert! Falls ein Serielles / USB -Gateway verwendet wird ist die Empfehlung, das via knxd-daemon einzubinden und die Modes: M,S oder T zur Verbindung knxd->FHEM zu verwenden.
* '''S -Socket Mode:''' Verbindet mittels UNIX_Socket zum knxd - Funktionert nur wenn sowohl FHEM als auch knxd am selben System laufen! Getestet wurde mit knxd-Verion 0.14.30. (Funktioniert definitiv NICHT mit knxd Version 0.10.0)
* '''X - Dummy Mode:''' Mode zum Testen ohne KNX-GW (und für ganz spezielle Fälle...)

=====IP-Adresse/Hostname:Port=====
Hostnamen sind unterstützt im Mode H und T.

Default/Standard Multicast Adresse (Mode M) ist: 244.0.23.12

Default/Standard Port für Mode H und M ist 3671, für Mode T 6720.

Default Socket path (Mode S) : /var/run/knxd (knxd-Version: 0.10.0) oder /run/knx (knxd-Version: 0.14.46) oder /var/run/knx (knxd-Version: 0.14.46), am besten in /etc/knxd.conf nachschauen!

=====Phy-Adresse=====
Das ist die Physikalische Adresse, die das KNX-Gateway bzw. knxd für Clients am LAN (also auch FHEM) bereitstellt. Der Wert sollte (bei Verwendung knxd) dem -E Parameter (Pool) in der knxd-Konfiguration entsprechen.

Alle Parameter sind verpflichtend! Bitte sicherstellen, dass es nur einen Kommunikationspfad zwischen dem KNX-Gateway und FHEM gibt! Das ist am sichersten erreichbar, wenn es in FHEM '''nur ein IO-Device''' (TUL/KNXTUL/KNXIO) für den KNX-Bus gibt.
====Definitions-Beispiele====
<syntaxhighlight lang="text">
define myKNXGW KNXIO H 192.168.1.201:3671 0.0.51
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.51
define myKNXGW KNXIO S /var/run/knx 0.0.51
define myKNXGW KNXIO T 192.168.1.200:6720 0.0.51
</syntaxhighlight>
Siehe auch {{Link2CmdRef|Anker=KNXIO}}.

Empfohlene Parameter für knxd Konfiguration: (üblicherweise zu finden: /etc/knxd.conf)
<syntaxhighlight lang="text">
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -b ipt:192.168.xx.yy" # connect to a knx-GW with ip-addr
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -R -S -single -b tpuarts:/dev/ttyxxx" # connect to a serial/USB KNX GW
KNXD_OPTS="-e 0.0.50 -E 0.0.51:8 -D -T -S -b ip:" # knxd acts as multicast client (connect to other knxd or KNX-Router with MC support)
</syntaxhighlight>Der Parameter '''-e 0.0.50''' definiert die phy-Addresse des Gateways, '''-E 0.0.51:8''' definiert einen Pool von 8 Phy-Addr. für Clients am LAN! (FHEM ist ein Client am LAN aus KNX Sicht! )

Die Parameter '''-R -S''' aktivieren den Multicast Support, '''-T -S''' den Tunnel Support im knxd. '''-D''' aktiviert Autodiscovery, wird allerdings von FHEM/KNXIO nicht verwendet, aber von der ETS-Software!

Der '''-S''' Parameter muss immer als letztes der Server Parameter (-D -T -R) stehen!

Siehe auch [[Knxd|knxd-Wiki]]

=== Attribute ===
* '''disable''' - ident zum FHEM Standard - kein Senden / Empfangen möglich.
* '''verbose''' - ident zum FHEM Standard - bestimmt welche/wieviele Meldungen ins Log geschrieben werden.

== Matrix - Modes<->Produkte ==
Die Tabelle soll die möglichen KNXIO-modes für KNX-GW's bzw. KNX-Router zeigen. Entstanden (und hoffentlich erweitert...) durch eigene Erfahrung und Tests bzw. auch aus Feedback aus dem Forum. Verwendete Produkt-Bezeichnungen können geschützte Namen sein, Diese werden hier ausschließlich verwendet um die Kompatibilität zum KNXIO-Modul darzustellen. Info über Produkte und ErfolgsMeldungen, aber auch Korrekturen sind willkommen, entweder direkt hier hinzufügen oder via Forum!
{| class="wikitable"
|+
!Produkt
!KNXIO-mode
!Kommentar
|-
|knxd
|M S T
|knxd -daemon (getestet ab V.0.10.0),
Mode S nur falls knxd am selben host läuft. (getested ab ab V.0.14.30)
|-
|Weinzierl IP731
|H
|4 Tunnel
|-
|Hager TYF120
|H
|? Tunnel
|-
|MDT SCN-IP000.02
|H
|4 Tunnel
|-
|MDT SCN-IP100.02
|M H
|4 Tunnel
|-
|Enertex® KNX IP Secure Router
|M H
|kein support im secure Mode - H untested
|-
|
|
|
|-
|Produkte mit seriellen od. USB Schnittstellen
z.B: TUL-Stick, ROT; usw...
| -
|Nur über knxd unterstützt
|}

== Umstellung von TUL oder KNXTUL Modul ==
Vorgangsweise: Config sichern! Bestehende TUL/KNXTUL - Definition löschen und neue KNXIO - Definition anlegen. FHEM restart!

Auf Grund der Änderung des Namens kann es passieren, dass im '''Reading IODev''' der KNX-Geräte nach wie vor das bisherige IO-Device (z.b: myTUL) steht.

Damit würde das Senden von FHEM -> KNX nicht funktionieren. Abhilfe schaftt das definieren vom '''Attribut IODev''' für alle KNX-Geräte, z.B so:<syntaxhighlight lang="text">
attr TYPE=KNX IODev myKNXGW
</syntaxhighlight>Das '''Attribut IODev''' kann nach einem weiteren restart vom FHEM wieder gelöscht werden! <syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Es sollte jetzt das '''Reading IODev''' in den KNX-Geräten auf das neue KNXIO-Gerät gesetzt sein! Das wird ab jetzt auch für künftige FHEM Starts verwendet.

=== TUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myTUL TUL eibd:192.168.5.246:6720 5.1.251
..wird:
define myKNXGW KNXIO T 192.168.5.246:6720 5.1.251
</syntaxhighlight>

=== KNXTUL-Modul ===
<syntaxhighlight lang="text">
Aus:
define myKNXTUL KNXTUL 0.0.252
..wird:
define myKNXGW KNXIO M 224.0.23.12:3671 0.0.252
</syntaxhighlight>

== Bekannte Probleme ==

==== Timing Problem Mode H ====
Wie bereits erwähnt, dieser Mode stellt hohe Ansprüche an das Antwortzeitverhalten von FHEM. Jede empfangene und gesendete Message muss in weniger als 1 Sekunde bestätigt werden. Falls FHEM länger mit anderen Modulen beschäftigt ist, gibt das Probleme. Typische Module, die Probleme machen können, sind (u.A.): SVG, Onewire, HTTPMOD, usw...

Typische Meldungen im Log:<syntaxhighlight lang="text">
2021.12.13 00:00:06.506 3: <device> [KNXIO_TunnelRequestTO 1216]: timeout - attempt resend
2021.12.13 00:00:08.023 3: <device> [KNXIO_TunnelRequestTO 1224]: timeout - sending disconnect request
2021.12.15 13:12:09.045 3: <device> [KNXIO_ReadH 414]: TunnelRequest received: duplicate message received (seqcntr= xxx) - ack it
2021.12.15 13:12:10.012 3: <device> [KNXIO_ReadH 426]: TunnelRequest received: out of sequence, (seqcntrRx= xxx seqcntrTx= yyy ) - no ack & discard
</syntaxhighlight>Eine mögliche Lösung: Mittels [[Apptime]] cmd: "apptime average" bzw. "apptime max" jene Funktionen/Module herausfinden, die viel Zeit in FHEM beanspruchen... Werte größer 500ms können die Kommunikation zwischen FHEM und dem KNX-GW massiv stören. Werte die mit "tmr_" beginnen, sind nicht ganz so kritisch, sollten aber jedenfalls unter 900ms sein.

Evtl hilft auch, die Anzahl Events zu reduzieren (Stichwort: event-on-change-reading).

Falls das nicht funktioniert, gibts noch die Möglichkeit, für das KNXIO-Modul eine eigene FHEM Instanz zu installieren und mittels FHEM2FHEM mit der Hauptinstanz zu verbinden.. In diesem Beispiel auf zwei Raspberrys im selben LAN. Sinnvollerweise beginnt man mit der Konfiguration von FHEM-B.

===== Konfiguration FHEM-A (Hauptinstanz): =====
Das ist jenes FHEM, wo bisher das KNXIO Modul und alle KNX-Devices definiert sind.<syntaxhighlight lang="text">
define <remoteDevice> KNXIO X # das ist ein dummy device,wird aber für die FHEM2FHEM definition benötigt

define <name_F2F> FHEM2FHEM <ip-addr:port> RAW:<remoteDevice> # verbindet zum telnet-dev auf FHEM-B
attr <name_F2F> keepaliveInterval 60
attr <name_F2F> reportConnected 1

</syntaxhighlight>'''Wichtig:''' <remoteDevice> muss in allen Definitionen (FHEM-A, FHEM-B) '''der gleiche Name''' sein! <ip-addr:port> ist die Adresse von FHEM-B, port ist der port aus der telnet-Definition.

Ändern des Attr IODev in allen KNX-definitionen: Attr IODev muss auf das FHEM2FHEM <name_F2F> Device zeigen. Entweder jedes KNX-device einzeln ändern, oder alle IODev Attribute in allen KNX-devices auf einmal löschen, mittels:<syntaxhighlight lang="text">
deleteattr TYPE=KNX IODev
</syntaxhighlight>Das ist kein Problem, (solange man nur EIN IO-device für KNX definiert hat), FHEM sucht beim start / defmod sich ein passendes IO-Device automatisch aus.

Die bisherige KNXIO-Definition löschen. Die sollte jetzt bereits in FHEM-B aktiv sein !

===== Konfiguration FHEM-B: =====
Starten mit minimal (default) Konfiguration, am besten nach Neu-Installation und fhem-update.

Hier wird das KNXIO-Modul konfiguriert, das mit dem KNX Gateway kommuniziert. Das ist exakt die gleiche def wie bisher in FHEM-A !

Es braucht aber zusätzlich noch einige Definitionen zur Kommunikation mit FHEM-A:<syntaxhighlight lang="text">
define <remoteDevice> KNXIO <mode> <GW-IP:GW-port> <phy-addr> # exakt gleiche Definition wie bisher in FHEM-A

define telnetPortKNX telnet <port> global # das kommuniziert mit dem FHEM2FHEM device auf FHEM-A
attr telnetPortKNX allowfrom (127.0.0.1|192.168.x) # little bit of security, replace x with yr. local network...

define allowed_telnetPortKNX allowed # little bit of security
attr allowed_telnetPortKNX allowedCommands iowrite,inform,trigger,quit
attr allowed_telnetPortKNX allowedIfAuthenticatedByMe 0
attr allowed_telnetPortKNX validFor telnetPortKNX

attr initialUsbCheck disable 1 # stört alle seriellen IO's (ausser CUL....)

attr autocreate ignoreTypes KNX_.* # we dont need/want KNX-devices on this FHEM
</syntaxhighlight>'''Empfohlen:''' Für die telnet definition nicht den Standard-port 7072 verwenden, sondern z.B: 7073.

'''Wichtig:''' Nach der Definition: save und shutdown/restart auf beiden FHEMs! Danach sollte das FHEM2FHEM-device connected zeigen, das KNXIO-device auf FHEM-A <remoteDevice> ebenfalls connected, wenn es ein passendes FHEM2FHEM Device gibt!

'''Keine weiteren Verbindungen''' zwischen den beiden FHEM machen, e.g: FHEM2FHEM im Log Modus, RFHEM, notifies., Telnet connections,...., -Das ergibt Chaos!

Es werden alle KNX-Messages zwischen FHEM-A und FHEM-B ausgetauscht!

Zur Verbesserung der Sicherheit könnte man das telnet-device UND das FHEM2FHEM-device jeweils mit Passwort (globalpassword) und/oder SSL versehen.

==== KNX im Docker Environment ====
Wie bekannt, unterstützt Docker in Bridge Konfiguration '''kein Broadcast / Multicast.''' Daher funktioniert KNXIO Mode M nicht im Docker! In diversen Foren wird daher host mode empfohlen.Alle anderen KNXIO-modes funktionieren im bridge Modus!

Der Host mode hat jedoch einige Nachteile, daher basierend auf {{Link2Forum|Topic=114284|LinkText=diesem Forum post}}, folgenden Lösung mittels macvlan:<syntaxhighlight lang="text">
docker network create -d macvlan -o parent=eth0 --subnet=192.168.5.0/24 --gateway=192.168.5.254 --ip-range=192.168.5.144/28 mymacvlannetwork
docker run -d --name fhemdocker --network=mymacvlannetwork --ip=192.168.5.144 -h cl-RPI4-d1 -v /opt/volumes/fhem:/opt/fhem fhem/fhem
</syntaxhighlight>Erstellen macvlan Network:

* '''eth0''' ist der name des Ethernet Interfaces an docker-host
* '''subnet / gateway''' dem Netzwerk Environment entsprechend.
* '''ip.range''' ein Adress-Bereich aus dem Netzwerk, (in diesem Beispiel 8 Addressen 192.168.5.144 - .151), diese '''dürfen nicht''' im DHCP Range oder durch statische Adressen bereits vergeben sein!
* '''mymacvlannetwork''' Name des macvlan

Docker run cmd:

* '''--name''' des containers
* '''--network''' referenz auf macvlan
* '''--ip''' eine (statische) Adresse aus den definierten ip-range Bereich
* '''-v''' Mapping von /opt/volumes/fhem (am Docker host) auf /opt/fhem (im Container) - dort wird z.B auch die fhem.cfg / logs / ... permanent gespeichert.
* '''fhem/fhem''' standard Image von docker hub

Erreichbar ist FHEM auf: <nowiki>http://192.168.5.144:8083/fhem</nowiki> Alle ports die FHEM öffnet sind von überall (Ausnahme Docker-host) im eigenen Netz erreichbar.

Nicht erreichbar ist vom docker host <-> FHEM und umgekehrt! Das ist eine Docker/macvlan Einschränkung.

Falls die Namensauflösung (--name fhemdocker) im Netz nicht funktioniert, kann der name z.B. in der Fritzbox statisch definiert werden.

== Links ==
Info zum Thema KNXD Konfiguration (beim Author): [https://github.com/knxd/knxd/wiki KNXD Wiki]

[[Knxd|Knxd-Wiki]]

[[FHEM2FHEM|FHEM2FHEM-Wiki]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2023-11-21T08:17:24Z

Erwin111: /* Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:EinAus:set:nosuffix 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'Status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name EinAus off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "Status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird [[AutoShuttersControl|hier]] behandelt. Hier werden nur jene Definitionen gezeigt, die KNX spezifisch sind.

Etliche Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: Autom. Hinauf/Runter fahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstion auch Beschattung. Das ASC Modul sendet Werte von 0-100 um die JalousiePosition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device überein stimmen

ASC_CommandTemplate: so muss der set command für das KNX-device zusammengestellt werden - also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist um die korrekte Funktion des ASC.Moduls zu erhalten.

Um die Funktion zu Testen, kann man den command: '''set <ASC_device> wiggle''' verwenden. Die Jalousie sollte sich um 5% (default) bewegen und nach 60 Sekunden um 5% in die Gegenrichtung.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2023-11-21T08:00:44Z

Erwin111: /* Jalousie / Rolladen */ Erweiterung ASC Funktion

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:EinAus:set:nosuffix 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'Status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name EinAus off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "Status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Jalousie / Rolladen - Erweiterung mit ASC (AutoShuttersControl) ====
Das ist eine Erweiterung des vorigen Beispiels. Die grundsätzliche Funktionalität von ASC wird [[AutoShuttersControl|hier]] behandelt. Hier werden nur jene Definitionen gezeigt, die KNX spezifisch sind.

Etliche Funktionen des ASC.Moduls sind in einem KNX.System möglicherweise bereits vorhanden, z.B.: Autom. Hinauf/Runter fahren bei diversen Alarmen (Wind,Regen,Frost, Fenster/Tür offen) oder in Kombination mit einer Wetterstion auch Beschattung. Das ASC Modul sendet Werte von 0-100 um die JalousiePosition zu setzen und erwartet im ASC_Pos_Reading Attribut die aktuelle Position.<syntaxhighlight lang="text">
attr Jal_Kueche ASC 1
attr Jal_Kueche ASC_Closed_Pos 100
attr Jal_Kueche ASC_Open_Pos 0
attr Jal_Kueche ASC_CommandTemplate set $name position $pos
attr Jal_Kueche ASC_Pos_Reading posstatus
</syntaxhighlight>ASC_Open_Pos, ASC_Closed_Pos: 0 bedeutet Jalousie ist oben, 100 unten.

ASC_Pos_Reading: das ist der Ist-Wert der Jalousie. Muss mit dem Readingnamen im KNX-Device überein stimmen

ASC_CommandTemplate: so muss der set command für das KNX-device zusammengestellt werden - also z.B: '''set Jal_Kueche position 50'''

Beim Testen wurde festgestellt, dass nach Definition/Änderung von Attributen u.U. ein FHEM Restart erforderlich ist um die korrekte Funktion des ASC.Moduls zu erhalten.

==== Slider - mit Rückmeldung '''und Wert umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

Einrichten von eibd für das Weinzierl IP 730 Interface

2023-10-26T16:14:14Z

Erwin111:

= eibd mit dem Weinzierl IP 730 Interface einrichten =
Damit FHEM auf den KNX Bus zugreifen kann, wird ein passendes [[Interface]] benötigt.

Es gibt:
* RS232
* USB
* IP

Im Folgenden wird die Einrichtung von eibd mit dem Weinzierl IP 730 Interface beschrieben.

Der eibd wurde weiterentwickelt und heisst nun [[knxd]]. Er kann nun auf aktuellen debian systemen mittels "apt-get" installiert werden und ist auf der Seite [[knxd]] im Detail beschrieben.

Das Weinzierl IP 730 Interface kann bis zu fünf Verbindungen gleichzeitig handhaben.
Die erste physikalische Adresse wird im Kommunikation Menü konfiguriert. Jede weitere wird durch das drücken des Programmknopfes generiert.
Dabei gilt: jedes drücken entspricht letzte phy-addr +1. Daher empfiehlt es sich, mit der ersten Adresse (0.0.51) zu beginnen.

In Verbindung mit FHEM funktionieren die Parameter:

KNXD_OPTS="-e 0.0.50 -E 0.0.51:5 -D -T -R -S -b ipt:<IP vom 730>"

Die Definition in der FHEM [[Konfiguration]] sieht dann z.B. so aus (weitere Beispiele zur Konfiguration sind auf der Seite [[KNXIO]] verfügbar):

define myKNXGW KNXIO T localhost:6720 0.0.51
[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX

2023-10-04T11:54:56Z

Erwin111: Migration EIB -> KNX

{{Infobox Modul
|ModPurpose=Unterstützung des KNX Feldbus in FHEM
|ModType=d
|ModForumArea=KNX/EIB
|ModFTopic=122582
|ModTechName=10_KNX.pm
|ModOwner=Erwin ({{Link2FU|115|Forum}}/[[Benutzer Diskussion:Erwin111|Wiki]])
}}
Das Modul [[KNX]] implementiert die Unterstützung für den Gebäudeautomations-Feldbus [https://de.wikipedia.org/wiki/KNX-Standard KNX] (eine Weiterentwicklung von EIB) innerhalb von FHEM.

== Voraussetzungen ==
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das KNX-Modul umzusteigen!
Unterstützung gibst in diesem Thread: https://forum.fhem.de/index.php/topic,126994.0.html im Forum|RNTyp=Warn|style=}}

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. Das IO-Modul: [[KNXIO|'''KNXIO''']] ersetzt die bisher verfügbaren Module '''TUL''' und '''KNXTUL''', es unterstützt die (meisten) Funktionen der bisherigen IO-Module und bietet zusätzlich weitere Kommunikationsoptionen.

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. [https://github.com/knxd/knxd/wiki knxd wiki]

== Anwendung ==
=== Define ===
<syntaxhighlight lang="text">
define <name> KNX <group>:<dpt>[:[gadName]:[set|get|listenonly]:[nosuffix]] [<group>:<dpt> ..] [<group>:<dpt> ..]
</syntaxhighlight>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: {{Link2CmdRef|Anker=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 <code>get Wohnzimmer desired-temperature</code> ü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 {{Link2CmdRef|Anker=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: <syntaxhighlight lang="text">
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
</syntaxhighlight>

==== ESF-import oder: Wie bekomme ich alle GA's aus der ETS in FHEM definiert? ====
Dazu gibts ein XLSX [https://forum.fhem.de/index.php/topic,128532.msg1231776.html#msg1231776 im Forum] , welches automatisiert FHEM definitionen erstellt. Danke an JooNey, der dafür auch Unterstützung im Forum leistet!

=== 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.
* '''putCmd''' - Falls dieses Attr gesetzt ist wird ein read-request vom KNX Gerät beantwortet. Der Rückgabe-Wert wird mit einer perl Funktion bestimmt.
* '''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 {{Link2CmdRef|Anker=KNX-attr}}.

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

Die Syntax:<syntaxhighlight lang="text">
set <device> <gadName> <wert>
set <device> <wert>
set <device> g1 <wert>
</syntaxhighlight>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: {{Link2CmdRef|Anker=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.

== Umstellung EIB -> KNX Modul ==
Nachdem das EIB-Modul seit März 2018 nicht mehr upgedatet wurde und deprecated ist, möchte ich dazu motivieren auf das aktuelle KNX-Modul umzustellen.

Ausführliche Erklärungen, Beispiele im [https://forum.fhem.de/index.php?topic=126994.0 FHEM Forum]

== Anwendungsbeispiele ==
Eine umfangreiche Sammlung von Anwendungsbeispielen ist auf der Seite '''[[KNX Device Definition - Beispiele]]''' zusammengestellt.

== Bekannte Probleme ==

== Links ==

[[Kategorie:EIB/KNX]]

KNXIO

2023-10-03T12:25:36Z

Erwin111: /* Timing Problem Mode H */

KNX Device Definition - Beispiele

2023-09-06T07:28:38Z

Erwin111: /* on/off Device - Treppenlicht */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== on/off Device - Treppenlicht ====
Üblicherweise haben KNX-Aktoren eine Staircase (Treppenlicht) Funktion, die mittes ETS programmiert werden kann. Falls das nicht der Fall ist, oder man die Zeitdauer dynamisch vorgeben will, könnte das so aussehen:<syntaxhighlight lang="text">
defmod dpt1Treppenlicht KNX 14/1/1:dpt1:EinAus:set:nosuffix 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1Treppenlicht devStateIcon on-for-timer.*:on-for-timer@red:off on:on@red:off
attr dpt1Treppenlicht stateCmd { if ($gadName eq 'Status' && $state eq 'on') {
fhem ("sleep 15.0 $name quiet; set $name EinAus off");
return 'on-for-timer';
}
return $state;
}
</syntaxhighlight>stateCmd reagiert auf die "Status = on" -msg vom Aktor, startet einen 15 Sekunden Timer und schaltet nach Ablauf auf off. Gleichzeitig wird das DevstateIcon auf "on-for-timer" gesetzt.

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Slider - mit Rückmeldung '''und Wert Umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2023-09-04T05:25:19Z

Erwin111: /* Slider - einfach */

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen@set:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position@set:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind@set:slider,0,1,100 slat@set:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp@set:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp@set:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position@set:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Slider - mit Rückmeldung '''und Wert Umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe@set:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white@set:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2023-08-13T13:07:13Z

Erwin111: dpt251GUI.png positionierung geändert

=== Vorwort ===
{{Randnotiz|RNTyp=Warn|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen! Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen! Tips zur Migration sind auch in {{Link2Forum|Topic=126994|LinkText=diesem Forenthema}} zu finden.}}
Hier soll ein Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels [[notify]], [[DOIF]], usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Infos, Tips & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>
Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>
Hier gibt es zwei GA-Adressen, eine zum Schalten und die zweite für die Rückmeldung vom Aktor (muss natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="Perl">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>
Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>
Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um drei Zusände darzustellen (on,off,steuern).

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher:
<syntaxhighlight lang="Perl">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>
Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so:
<syntaxhighlight lang="Perl">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}
</syntaxhighlight>
und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="Perl">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen:slider,0,5,100
</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>
Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für zwei Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GAs der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet), kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position-set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position:slider,0,5,100
</syntaxhighlight>
Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="Perl">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind:slider,0,1,100 slat:slider,0,10,100
</syntaxhighlight>
Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.
<syntaxhighlight lang="Perl">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
 
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>
Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>
Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmds lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>
Die entsprechenden set-cmds lauten:
<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>
Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings zwei Subroutinen in der 99_myUtils!
<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position:slider,0,5,100
</syntaxhighlight>.. und die beiden subs in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.
<syntaxhighlight lang="Perl">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}
</syntaxhighlight>
Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Slider - mit Rückmeldung '''und Wert Umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:
<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>
Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="Perl">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe:slider,0,1,8
</syntaxhighlight>
Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.
[[Datei:KNX_dpt251GUI.png|rechts|503x503px]]

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus zwei Widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt zwei "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.

<syntaxhighlight lang="Perl">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul? ===
Im KNX-Modul sind (fast) alle DPTs unterstützt, die in den frei verfügbaren Standarddokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPTs, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im Wesentlichen unterscheiden sich die sub-DPTs z.B. dpt9.020 von den "Haupt-DPTs" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:
<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>
und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:
<syntaxhighlight lang="Perl">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>
Falsch definierte DPTs (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene Konfiguration ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.B. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:
<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine Syntaxfehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.B. im stateCmd aufgerufen:
<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>
Das hat dann auch den Vorteil, dass die sub-Routine von mehreren Devices verwendet werden kann!

[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]

KNX Device Definition - Beispiele

2023-08-07T07:09:37Z

Erwin111: /* RGBW Steuerung (dpt251.600) */

=== Vorwort ===
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen!
Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen!
Tips zur Migration sind auch im [https://forum.fhem.de/index.php/topic,126994.0.html Forum] zu finden.|RNTyp=Warn}}

Hier soll mit eine Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels notify, doif, usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Info's, Tip's & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>Hier gibt es 2 GA-Adressen, eine zum Schalten und die 2te für die Rückmeldung vom Aktor (muß natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="text">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um 3 Zusände darzustellen (on,off,steuern).

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher: <syntaxhighlight lang="text">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so: <syntaxhighlight lang="text">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}

</syntaxhighlight>und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="text">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen:slider,0,5,100

</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für 2 Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GA's der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: Falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat, (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet, kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position-set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position:slider,0,5,100
</syntaxhighlight>Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="text">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind:slider,0,1,100 slat:slider,0,10,100
</syntaxhighlight>Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.<syntaxhighlight lang="text">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmd's lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>Die entsprechenden set-cmd's lauten:<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings 2 sub-routinen in der 99_myUtils!<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position:slider,0,5,100
</syntaxhighlight>.. und die beiden sub's in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.<syntaxhighlight lang="text">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}

</syntaxhighlight>Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Slider - mit Rückmeldung '''und Wert Umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="text">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe:slider,0,1,8
</syntaxhighlight>Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.

==== RGBW Steuerung (dpt251.600) ====
Die GUI für diesen dpt ist komplex, weil sie aus 2 widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt 2 "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.
[[Datei:KNX_dpt251GUI.png]]<syntaxhighlight lang="text">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal($NAME,"state","00000000"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal($NAME,"state","00000000"),0,6),round($1*2.55,0)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = round(hex(substr($state,6,2))/2.55,0);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul ? ===
Im KNX-Modul sind (fast) alle DPT's unterstützt, die in den frei verfügbaren Standard-Dokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPT's, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im wesentlichen unterscheiden sich die sub-DPT's z.B. dpt9.020 von den "Haupt-DPT's" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:<syntaxhighlight lang="text">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>Falsch definierte DPT's (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene config ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.b. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine syntax-Fehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.b. im stateCmd aufgerufen:<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>Das hat dann auch den Vorteil, dass die sub-Routine von mehreren devices verwendet werden kann!
[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]
[[Kategorie:Gerätemodul]]

KNX Device Definition - Beispiele

2023-08-06T10:12:41Z

Erwin111: /* RGBW Steuerung (dpt251.600) */

=== Vorwort ===
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen!
Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen!
Tips zur Migration sind auch im [https://forum.fhem.de/index.php/topic,126994.0.html Forum] zu finden.|RNTyp=Warn}}

Hier soll mit eine Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels notify, doif, usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Info's, Tip's & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>Hier gibt es 2 GA-Adressen, eine zum Schalten und die 2te für die Rückmeldung vom Aktor (muß natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="text">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um 3 Zusände darzustellen (on,off,steuern).

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher: <syntaxhighlight lang="text">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so: <syntaxhighlight lang="text">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}

</syntaxhighlight>und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="text">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen:slider,0,5,100

</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für 2 Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GA's der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: Falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat, (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet, kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position-set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position:slider,0,5,100
</syntaxhighlight>Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="text">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind:slider,0,1,100 slat:slider,0,10,100
</syntaxhighlight>Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.<syntaxhighlight lang="text">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmd's lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>Die entsprechenden set-cmd's lauten:<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings 2 sub-routinen in der 99_myUtils!<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position:slider,0,5,100
</syntaxhighlight>.. und die beiden sub's in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.<syntaxhighlight lang="text">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}

</syntaxhighlight>Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Slider - mit Rückmeldung '''und Wert Umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="text">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe:slider,0,1,8
</syntaxhighlight>Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.

==== RGBW Steuerung (dpt251.600) ====
Diese GUI für diesen dpt ist komplex, weil sie aus 2 widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt 2 "Hilfs-readings" (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.
[[Datei:KNX_dpt251GUI.png]]<syntaxhighlight lang="text">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal("dpt251tst","state","aa"),6,2)) . "' ,
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal("dpt251tst","state","aa"),0,6),int($1*2.555)) . "' },
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},
}
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);
my $white = sprintf('%d',hex(substr($state,6,2))/2.55);
fhem("sleep 0.1; setreading $name rgb $rgb; setreading $name white $white");
return $state;
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul ? ===
Im KNX-Modul sind (fast) alle DPT's unterstützt, die in den frei verfügbaren Standard-Dokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPT's, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im wesentlichen unterscheiden sich die sub-DPT's z.B. dpt9.020 von den "Haupt-DPT's" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:<syntaxhighlight lang="text">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>Falsch definierte DPT's (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene config ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.b. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine syntax-Fehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.b. im stateCmd aufgerufen:<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>Das hat dann auch den Vorteil, dass die sub-Routine von mehreren devices verwendet werden kann!
[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]
[[Kategorie:Gerätemodul]]

KNX Device Definition - Beispiele

2023-08-06T10:08:36Z

Erwin111: neu: RGBW

=== Vorwort ===
{{Randnotiz|RNText=Hinweis: Das EIB-Modul ist seit 2018 deprecated und wird auch nicht mehr gewartet. Es ist daher dringend empfohlen, auf das [[KNX]]-Modul umzusteigen!
Mit diesen Beispielen sollte auch der Umstieg auf das KNX-Modul etwas leichter fallen!
Tips zur Migration sind auch im [https://forum.fhem.de/index.php/topic,126994.0.html Forum] zu finden.|RNTyp=Warn}}

Hier soll mit eine Austausch von funktionierenden Beispielen aus dem KNX Bereich stattfinden. Es geht um die Definition, die Darstellung im FHEM-Web und um die Weiterverarbeitung mittels notify, doif, usw.

Viele Anfragen im Forum beziehen sich auf Probleme bei der Definition, Darstellung und "Weiterverarbeitung" von KNX-Geräten. Alle User sind eingeladen, mit weiteren Beispielen mitzuwirken. Im ersten Schritt werden einige Beispiele aus der [https://fhem.de/commandref.html#KNX Command-Referenz] hierher übertragen, auch um die Command-Ref (in einem zweiten Schritt) etwas kompakter zu gestalten.

Die [https://fhem.de/commandref.html#KNX Command-Referenz] ist nach wie vor die aktuellste (und verbindliche) Dokumentation des Moduls. Hier sollen zusätzliche Info's, Tip's & Tricks gegeben werden.

Generelle Hinweise zum KNX Modul sind hier auf der Modulbeschreibungsseite [[KNX]] zu finden.

=== Beispiele ===
==== on/off Device - einfach ====
<syntaxhighlight lang="text">
define Lampe1 KNX 14/0/1:dpt1
</syntaxhighlight>Einfachstes KNX-Device ohne Alias und Rückmeldung.

==== on/off Device - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Lampe2 KNX 14/1/1:dpt1:EinAus 14/2/1:dpt1:Status:listenonly
attr Lampe2 webCmd EinAus
# attr Lampe2 webCmd :
attr Lampe2 stateFormat Status-get
attr Lampe2 devStateIcon off:li_wht_off:on on:li_wht_on:off
</syntaxhighlight>Hier gibt es 2 GA-Adressen, eine zum Schalten und die 2te für die Rückmeldung vom Aktor (muß natürlich via ETS so programmiert sein!).

Zusätzlich hat jede GA-Adresse nun einen Alias (=gadName), z.B. EinAus, Status. Das Attr "webcmd EinAus" erzeugt ein Pulldown Menü das die jeweilige Funktion ausführt. Falls man kein Pulldown Menü will, nimmt man die 2te Variante von webCmd und klickt auf das DeviceIcon um Ein/Aus zu schalten. DevStateIcon hat den Sinn, damit Icons den Zustand darstellen und beim anklicken die jeweilige Funktion ausführen. Die listenonly Option verhindert, dass ein Set- oder Get-cmd im FHEMWeb dargestellt wird. - Set oder Get sind auf diesen Alias dann nicht möglich!

==== on/off Device - blinken ====
<syntaxhighlight lang="text">
define dpt1blink KNX 14/1/1:dpt1:Blinker:set:nosuffix
attr dpt1blink comment blink example
attr dpt1blink devStateIcon on:sprinkler_icon@red:off off:sprinkler_icon@green:on
attr dpt1blink eventMap {usr=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'Blinker blink $1 $2'}, fw=>{'^(?:.*)?blink.([\d])[\s,]([\d])'=>'blink'} }
attr dpt1blink widgetOverride blink@set:widgetList,2,textField,Anzahl_blinks,2,textField,Dauer(sec) Blinker@set:widgetList,4,select,on,off,blink,2,textField,Anzahl_blinks,2,textField,Dauer(sec)
</syntaxhighlight>Ein Beispiel, wie man ein KNX-Geräte blinken lassen kann. Extensive Nutzung der Möglichkeiten vom attr eventmap und widgetoverride!

==== on/off Device - mit verzögerter Rückmeldung ====
Es gibt KNX-Aktoren, die erst nach erfolgreicher Ausführung (mit Verzögerung) eine Rückmeldung schicken. Bsp: Großer Drehstrom Motor mit Anlaufstrom-Begrenzung. Nach einem set-cmd (von FHEM) wird vorerst ein hourglass-icon dargestellt, solange bis die Rückmeldung vom KNX-Aktor kommt.<syntaxhighlight lang="text">
define dpt1_1tst KNX 14/1/1:dpt1:EinAus:set 14/2/1:dpt1:Status:listenonly:nosuffix
attr dpt1_1tst devStateIcon on:general_an:off off:general_aus:on steuern.*:hourglass:off
attr dpt1_1tst stateRegex /EinAus-set/steuern-/ /EinAus-get//
</syntaxhighlight>Gleichzeitig ein Beispiel zu stateRegex Verwendung: der 1. Teil muss dem reading[:value] entsprechen, Im konkreten Fall übersetzt das stateRegex "EinAus-set[:value]" nach "steuern-<value> im state-reading, Ein EinAus-get wird ignoriert! Damit kann das state-reading nicht on oder off werden, außer es kommt ein Status von der GA: 14/2/1. Das wird im devStateIcon genutzt, um 3 Zusände darzustellen (on,off,steuern).

==== Sensor - mit Umrechnung ====
Ein Windspeed Sensor sendet einen dpt9 Wert in Meter/Sekunde (nach ISO). Nachdem die gebräuchliche Einheit für Windgeschwindigkeiten km/h sind, muss also umgerechent werden. Das kann mittels Userreading passieren, geht aber auch einfacher: <syntaxhighlight lang="text">
defmod Windspeed KNX 14/0/9:dpt9.005:get:nosuffix
attr Windspeed stateCmd {return sprintf("%.1f",ReadingsNum($name,'g1',0)*3.6);;}
attr Windspeed stateFormat state km/h
</syntaxhighlight>Im reading '''g1''' steht die WIndspeed in m/s, im reading '''state''' (siehe stateCmd) die Windspeed in km/h - ohne Einheit, im Internal '''STATE''' die Windspeed mit Einheit.

Will man jedoch auch im reading '''state''' die Einheit haben, adaptiert man das stateCmd Attribute z.b. so: <syntaxhighlight lang="text">
attr Windspeed stateCmd {return sprintf("%.1f km/h",ReadingsNum($name,'g1',0)*3.6);;}

</syntaxhighlight>und lässt das Attr. stateFormat weg.

==== Dimmer ====
[[Datei:Dimmer.png|mini|600x600px]]
Eine Steuerung für KNX-Dimmer. Die Bedienung kann sowohl über on/off, als auch über prozent-Helligkeit und über dimup/dimdown (jeweils 10%) erfolgen. Dazu sind insgesamt vier GA-Adressen definert, die im KNX-Aktor (mittels ETS) konfiguriert sind .

"EinAus" ist die GA für das senden von on/off, "Status" - die Rückmeldung vom Aktor, "Dimmen" ist die GA für das Senden von Helligkeitswerten (Range 0-100%), "Dimmstatus" die Rückmeldung vom Aktor.

Das devStateIcon wird grau bei state=off, gelb bei state=on oder bei state= >0.

Die [[eventMap]]-Syntax ist reichlich verwirrend, im Wesentlichen: ein klick auf "dimup" erhöht den Wert von "Dimmen" um 10%, "dimdown" reduziert um 10%.

stateCmd wird bei jedem Event aufgerufen, in diesem Fall: Wenn sich "EinAus" ändert, wird dieser Wert nicht nur in das reading EinAus geschrieben, sondern auch in das reading Dimmen, allerdings übersetzt: on =>100, off=>0. Damit zeigt der Slider jederzeit den richtigen Zustand an. Zusätzlich wird der Wert auch in das Reading state geschrieben. Weiters: ändert sich "Dimmstatus", wird dieser Wert auch in das reading Dimmen geschreiben, damit der Slider auch den richtigen Wert anzeigt (der Dimmer könnte ja auch ausserhalb von FHEM bedient werden...).

webCmd und widgetOverride bestimmen das Aussehen und die Funktion der Overview Zeile. <syntaxhighlight lang="text">
defmod Dimmer KNX 14/6/1:dpt1:EinAus:set:nosuffix\
14/7/1:dpt1:Status:listenonly:nosuffix\
14/6/5:dpt5.001:Dimmen:set:nosuffix\
14/7/5:dpt5.001:DimmStatus:listenonly:nosuffix

attr Dimmer devStateIcon devStateIcon off:li_wht_off:on on:li_wht_on:off 0.*:li_wht_off:on \d+.*:li_wht_on:off
attr Dimmer eventMap {usr=>{'^dimup'=> '" . sprintf("Dimmen %d",minNum(100,ReadingsNum($NAME,"Dimmen",0) + 10)) . "', \
'^dimdown' => '" . sprintf("Dimmen %d",maxNum(0,ReadingsNum($NAME,"Dimmen",0) - 10)) . "'}, \
fw=>{'^dimup'=> 'dimup', '^dimdown'=> 'dimdown'} }
attr Dimmer stateCmd { if ($gadName eq 'DimmStatus') {\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $state;;");; \
}\
elsif ($gadName eq 'EinAus') {\
my $val = ($state eq 'on')?'100':'0';;\
fhem ("sleep 0.05 quiet;;setreading $name Dimmen $val;;");;\
}\
return $state;;\
}
attr Dimmer webCmd :dimup:dimdown:Dimmen
attr Dimmer widgetOverride Dimmen:slider,0,5,100

</syntaxhighlight>

==== Garagentor Steuerung ====
Dieses Beispiel kann für die (noch immer) üblichen 1-Taster Garagentor-Steuerungen genutzt werden.

Die GA 14/1/100-aufzu ist einem Aktor zugeordnet, der den Garagentor-Taster simuliert.

Die GA 14/1/101-aufzu_status ist die übliche Rückmeldung vom Status des Aktors.

Die GA 14/1/102-Doorstatus ist mit dem Garagensensor (KNX-Input) Tor= zu/offen verknüpft. <syntaxhighlight lang="text">
defmod Garagentor KNX 14/1/100:dpt1.001:aufzu:set:nosuffix\
14/1/101:dpt1.001:aufzu_status:listenonly:nosuffix\
14/1/102:dpt1.019:Doorstatus:listenonly:nosuffix\

attr Garagentor IODev myKNXIO
attr Garagentor comment set door trigger for 1 second, Status des Tors wird durch GA "Doorstatus" bestimmt.
attr Garagentor devStateIcon closed:fts_garage_door_100@green:on open:fts_garage@red:on
attr Garagentor eventMap {usr=>{'on'=>'aufzu on-for-timer 2','aufzu off'=>'off'} }
attr Garagentor stateRegex /aufzu// /aufzu_status//
attr Garagentor webCmd :
attr Garagentor widgetOverride aufzu:on
</syntaxhighlight>Ein Klick auf das DeviceState-Icon bewirkt ein "Set on", das wird mittels eventMap auf "Set aufzu on-for-timer 2" geändert. Der KNX-Aktor schließt den entsprechenden Kontakt für 2 Sekunden, simuliert damt einen Taster. Das Attribut stateRegex verhindert, dass von aufzu und von aufzu_status GA's der Wert ins reading "state" geschrieben wird. Ist das Garagentor geöffnet, wird der Wert von GA Doorstatus "open" - was auch ins state-reading kopiert wird und damit das DevstateIcon als offen/geschlossen anzeigt.

Alternativ: Falls der KNX-Aktor eine "TreppenLicht Funktion" implementiert hat, (bei einem on wird eingeschaltet und nach x Sekunden augeschaltet, kann das Attribut eventMap komplett weggelassen werden.

"Doorstatus" muss nicht unbedingt ein KNX-Gerät sein, das könnte auch von einem anderen Device z.B.via notify gesetzt werden:<syntaxhighlight lang="text">
setreading Garagentor Doorstatus open/closed
</syntaxhighlight>

==== Slider - einfach ====
<syntaxhighlight lang="text">
define Slider_Test KNX 15/2/2:dpt5:Position
attr Slider_Test webCmd Position
attr Slider_Test widgetOverride Position-set:slider,0,5,100
</syntaxhighlight>

==== Slider - mit Rückmeldung ====
<syntaxhighlight lang="text">
define Slider2_Test KNX 15/2/2:dpt5.001:Position:set:nosuffix 15/2/3:dpt5.001:PosStatus:get:nosuffix
attr Slider2_Test stateCmd { fhem "sleep 0.05 quiet;; setreading $name Position $state" if ($gadName eq 'PosStatus');; return $state;; }
attr Slider2_Test webCmd Position
attr Slider2_Test widgetOverride Position:slider,0,5,100
</syntaxhighlight>Das Attr stateCmd setzt den Wert der vom Aktor kommt - zusätzlich in das reading 'Position', damit der Slider immer auch die aktuelle Position anzeigt. Die doppelten semicolons sind aus parsing Gründen nötig. Falls man das Attribut über Device-Detail-view setzt, sind nur einfache ; nötig!

==== Zwei Slider mit Rückmeldung ====
[[Datei:KNX dpt5tst.png|rechts|rahmenlos|450x450px]]
Z.B. für eine Jalousie mit Lamellensteuerung. Das ist eine Erweiterung des vorigen Beispiels.<syntaxhighlight lang="text">
define dpt5test KNX 9/1/1:dpt5.001:blind:set:nosuffix 9/1/2:dpt5.001:blindStatus:listenonly:nosuffix
9/1/3:dpt5.001:slat:set:nosuffix 9/1/4:dpt5.001:slatStatus:listenonly:nosuffix
attr dpt5test devStateIcon {Jal_devStateIcon()}
attr dpt5test room KNXtest
attr dpt5test stateCmd { if ($gadName =~ /(.*)Status/x) {
fhem ("sleep 0.05 quiet; setreading $name $1 $state");
}
return $state;
}
attr dpt5test stateFormat 1:blind
 
2:slat
attr dpt5test webCmd blind:slat
attr dpt5test webCmdLabel Blind
:Slat
attr dpt5test widgetOverride blind:slider,0,1,100 slat:slider,0,10,100
</syntaxhighlight>Dazu braucht es noch eine sub in 99_myUtils.pm (siehe auch Beispiel Jalousie / Rolladen). Der Trick liegt in der indizierten Variante von stateFormat (1:blind,...), damit wird auch in devStateIcon dieser Index ausgewertet! Leider gibts für die Lamellen-Stellung nur 3 Icons, für die Stellungen: 0%,50%,100%.<syntaxhighlight lang="text">
## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
"block.off: " .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'1.100.*:fts_shutter_100 1.1\d.*:fts_shutter_10 ' .
'1.2\d.*:fts_shutter_20 1.3\d.*:fts_shutter_30 ' .
'1.4\d.*:fts_shutter_40 1.5\d.*:fts_shutter_50 ' .
'1.6\d.*:fts_shutter_60 1.7\d.*:fts_shutter_70 ' .
'1.8\d.*:fts_shutter_80 1.9\d.*:fts_shutter_90 ' .
'1.\d.*:fts_window_2w ' .
'2.100.*:fts_blade_arc_close_100 ' .
'2.\d\d.*:fts_blade_arc_close_50 ' .
'2.\d.*:fts_blade_arc_close_00 ';
return $iconstring;
}
</syntaxhighlight>

==== RaumThermostat / HeizungsAktor ====
[[Datei:Fhemwiki KNX - RaumThermostat.png|rechts|rahmenlos|674x674px]]
<syntaxhighlight lang="text">
define XXXZimmer_Heizung KNX 5/0/52:dpt9:solltemp:set:nosuffix 5/0/53:dpt9:solltemp_ist:get:nosuffix 5/0/50:dpt9:temperature:get:nosuffix 5/0/51:dpt5.001:valvepos:get:nosuffix
attr XXXZimmer_Heizung comment GAs: SollTemp-schreiben, SollTemp-lesen, IstTemp, ValvePosition
attr XXXZimmer_Heizung stateFormat temperature °C, Soll: solltemp_ist °C, Ventil: valvepos
attr XXXZimmer_Heizung webCmd solltemp
attr XXXZimmer_Heizung webCmdLabel SollTemperatur
attr XXXZimmer_Heizung widgetOverride solltemp:18.0,18.5,19.0,19.5,20.0,20.5,21.0,21.5,22.0,22.5,23.0,23.5,24.0,24.5,25.0 solltemp_ist:noArg temperature:noArg
attr XXXZimmer_Heizung widgetOverride solltemp:slider,18,0.5,25,1 solltemp_ist:noArg temperature:noArg
</syntaxhighlight>Beispiel für einen RaumThermostat / Heizungsregler. Die Soll-Temperatur kann entweder mittels pull-down oder mittels slider eingestellt werden. Siehe die beiden Attribute widgetoverride... (nur eines davon verwenden!)

Falls '''solltemp_ist''' nicht zur Verfügung steht, kann es weggelassen werden. Funktion: Es könnte ja die SollTemperatur am Raumthermostat eingestellt worden sein!

'''valvepos''' ist der Prozentwert, den das Raumthermostat für das Ventil der FB-Heizung sendet.

==== Zeit und Datum ====
<syntaxhighlight lang="text">
define timedev KNX 0/0/7:dpt10:time 0/0/8:dpt11:date 0/0/9:dpt19:datetime
</syntaxhighlight>Hier sind alle Varianten von Zeit / Datum dargestellt. Die Empfänger müssen den jeweiligen DPT natürlich unterstützen!

die entsprechenden set-cmd's lauten:<syntaxhighlight lang="text">
# setze das Datum auf den Bus:
set timedev date now
set timedev date 01.11.2021

# setze die Zeit auf den Bus:
set timedev time now
set timedev time 18:33:44

# setze Datum und Zeit (gleichzeitig) auf den Bus:
set timedev datetime now
set timedev datetime 01.11.2020_18:33:44
</syntaxhighlight>

==== Text senden / empfangen ====
<syntaxhighlight lang="text">
define textdev KNX 0/0/9:dpt16:txt
</syntaxhighlight>Die entsprechenden set-cmd's lauten:<syntaxhighlight lang="text">
set textdev txt AbCdEfGhIjkLmN # send text to Bus (max 14 Char.)
set textdev txt >CLR< # delete text on the KNX display
</syntaxhighlight>

==== Fhem antwortet auf Read Request vom Bus ====
<syntaxhighlight lang="text">
define putDemo KNX 1/0/30:dpt9.001:temp 1/0/31:dpt9.001:humidity 1/0/32:dpt9:refVal

attr putDemo putCmd {ReadingsNum($name,'refVal-get',0) if ($gadName eq 'temp');}
</syntaxhighlight>Es sind 3 GA_Adressen definiert, FHEM antwortet allerdings nur auf einen read-request vom Bus wenn die 1/0/30 Adresse angesprochen wird, mit dem Wert der im refVal reading steht!

==== Jalousie / Rolladen ====
[[Datei:KNX JalKueche.png|rechts|rahmenlos|450x450px]]
Ein komplexes Beispiel, getestet mit einem Jal-Aktor von MDT. Ganz wichtig ist die GA: moving, der Aktor sendet on solange sich die Jalousie bewegt. Das ist ein Parameter, der mittels ETS konfiguriert werden kann. Ergebnis ist ein Device, dass jederzeit die Position anzeigt, Schlaltfllächen für Auf/Ab und einen Slider für's setzen der absoluten Position bietet. Dazu braucht es allerdings 2 sub-routinen in der 99_myUtils!<syntaxhighlight lang="text">
define Jal_Kueche KNX 5/1/53:dpt1.008:aufab:set:nosuffix
5/1/55:dpt1.010:stop:set:nosuffix
5/1/57:dpt1:moving:listenonly:nosuffix
5/1/58:dpt5.001:position:set:nosuffix
5/1/60:dpt5.001:posstatus:get:nosuffix
5/1/72:dpt1:block:set:nosuffix
5/1/65:dpt1:uppos:listenonly:nosuffix
5/1/66:dpt1:dnpos:listenonly:nosuffix

attr Jal_Kueche cmdIcon Auf:black_up Ab:black_down Stop:remotecontrol/black_btn_RED
attr Jal_Kueche comment GA's: aufab,stop,movestatus,posstatus,Setposition,block,uppos,dnpos
attr Jal_Kueche devStateIcon {Jal_devStateIcon()}
attr Jal_Kueche eventMap { usr=>{'Stop'=>'stop stop','Auf'=>'aufab up','Ab'=>'aufab down'} }
attr Jal_Kueche stateCmd {Jal_stateCmd($name,$gadName,$state)}
attr Jal_Kueche webCmd Auf:Ab:position
attr Jal_Kueche widgetOverride position:slider,0,5,100
</syntaxhighlight>.. und die beiden sub's in 99_myUtils.pm (Diese werden von allen Jalousien / Rolladen verwendet.<syntaxhighlight lang="text">
### Jalousie Utilities
## return string for stateCmd
## input: devicename, Gadname, state
sub Jal_stateCmd {
my ($dname,$gadname,$dstate) = @_;
my $newstate = '';
if (ReadingsVal($dname,'block','off') eq 'on' ) {
$newstate = 'block:on';
} elsif (ReadingsVal($dname,'moving','off') eq 'on' ) {
$newstate = 'moving';
Log3 $dname, 5, "in stateCmd-movingon: $dname, $gadname,$dstate,newstate: $newstate";
} else {
$newstate = int((ReadingsNum($dname,'posstatus',0)+5)/10) * 10;
}
return $newstate;
}

## return string for devStateIcon
## input: none
## return string
sub Jal_devStateIcon {
my $iconstring = 'block.on:fts_door_open@red ' .
'block.off: ' .
'wind.on:weather_wind@red ' .
'wind.off: ' .
'aufab.off:black_down:Ab ' .
'aufab.on:black_up:Auf ' .
'moving:fts_shutter_updown@red:Stop ' .
'100.*:fts_shutter_100 1\d.*:fts_shutter_10 ' .
'2\d.*:fts_shutter_20 3\d.*:fts_shutter_30 ' .
'4\d.*:fts_shutter_40 5\d.*:fts_shutter_50 ' .
'6\d.*:fts_shutter_60 7\d.*:fts_shutter_70 ' .
'8\d.*:fts_shutter_80 9\d.*:fts_shutter_90 ' .
'\d.*:fts_window_2w';
return $iconstring;
}

</syntaxhighlight>Die sub stateCmd berücksichtigt auch noch die GA: block - z.B. wenn Fenster/Tür offen ist oder einen einen WindAlarm!

==== Slider - mit Rückmeldung '''und Wert Umrechnung''' ====
Ein komplexer Fall, wo ein Hersteller zwar den dpt5 verwendet, aber sein "eigenes Zahlen-Format" implementiert hat. Konkret geht's um eine Lüftungsanlage, die Stufen 0 (=Aus) bis 8 (=Maximum) verwendet. Am Bus kommen / werden erwartet die folgenden Werte:<syntaxhighlight lang="text">
0 (Aus)->0, 1->31, 2->63, 3->95, ... , 8->255
</syntaxhighlight>Im FHEM-Web sollen aber die Stufen 0-8 verwendet werden.
<syntaxhighlight lang="text">
define KNXStufentest KNX 11/1/18:dpt5:StufeSoll:set:nosuffix 11/1/20:dpt5:StufeIst:get:nosuffix

attr KNXStufentest eventMap { usr => {'Aus' => 'StufeSoll 0', '^Ein' => 'StufeSoll ' . (3 * 32 - 1), '^Stufe (\d)' => '" . sprintf("StufeSoll %d",(($1 == 0)?0:($1 * 32 - 1)) ) . "' },
fw => {'^Ein' => 'Ein', '^Stufe (\d)' => 'Stufe' } }

attr KNXStufentest stateCmd { ($state,undef) = split(/\s/ix,$state);
my $stateC = int(($state + 1) / 32);
if ($gadName eq 'StufeIst') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
if ($gadName eq 'StufeSoll') {
fhem ("sleep 0.1;setreading $name Stufe $stateC");
}
return $state;
}
attr KNXStufentest webCmd Aus:Ein:Stufe
attr KNXStufentest widgetOverride Aus:noArg Ein:noArg Stufe:slider,0,1,8
</syntaxhighlight>Ankommende Messages (von Alias StufeIst) werden wie üblich im reading "StufeIst" (Werte: 0-255) gespeichert und '''zusätzlich''' umgerechnet und im reading "Stufe" (Wert: 0-8) gespeichert. Ein cmd vom User (Werte: 0-8) wird durch die eventMap umgerechnet und auf den Bus gesendet. Zusätzlich gibt's noch die Schaltflächen "Ein" und "Aus" . Auch diese Werde mittels eventMap auf Stufe 3(=Ein) bzw. Stufe 0(=Aus) umgerechnet. Die Syntax der eventMap ist gewöhnungsbedüftig, aber so funktioniert's! Was noch fehlt ist die Darstellung der Lüfterstufe mittels Icon.

==== RGBW Steuerung (dpt251.600) ====
Diese GUI für di4esen dpt ist komplex, weil sie aus 2 widgets besteht: '''colopicker,RGB''' und '''slider'''.

Die eventmap setzt die beiden Werte (RGB u. White), die jeweils von den widgets kommen, zusammen und sendet das Resultat an den Bus. Der stateCmd setzt 2 "Hilfs-readings (rgb,white), die aktuellen Basis-Werte für die widgets darstellen.
[[Datei:KNX dpt251GUI.png|mini]]
<syntaxhighlight lang="text">
define dpt251tst KNX 14/1/251:dpt251.600:set:nosuffix
attr dpt251tst eventMap {usr => {'^rgb.(.+)' => '" . sprintf("g1 %s%s",$1,substr(ReadingsVal("dpt251tst","state","aa"),6,2)) . "' , \
'^white.(.+)' => '" . sprintf("g1 %s%.2x",substr(ReadingsVal("dpt251tst","state","aa"),0,6),int($1*2.555)) . "' },\
fw => {'^rgb.(.+)' => 'rgb', '^white.(.+)' => 'white'},\
}\
attr dpt251tst stateCmd { my $rgb = substr($state,0,6);;\
my $white = sprintf('%d',hex(substr($state,6,2))/2.55);;\
fhem("sleep 0.1;; setreading $name rgb $rgb;; setreading $name white $white");;\
return $state;;\
}
attr dpt251tst webCmd rgb:white
attr dpt251tst widgetOverride rgb:colorpicker,RGB white:slider,0,1,100
</syntaxhighlight>

=== DPT nicht unterstützt im KNX Modul ? ===
Im KNX-Modul sind (fast) alle DPT's unterstützt, die in den frei verfügbaren Standard-Dokumenten definiert sind. Hersteller definieren manchmal eigene sub-DPT's, die dann möglicherweise nicht unmittelbar unterstützt sind.

Im wesentlichen unterscheiden sich die sub-DPT's z.B. dpt9.020 von den "Haupt-DPT's" z.B. dpt9 durch die angefügte Einheit, den min/max Werte-Bereich, die Skalierung oder einen Offset. Falls also ein Gerät eine 2Byte-float Wert senden will, dann könnte das so aussehen:<syntaxhighlight lang="text">
define dpt9test KNX 0/4/6:dpt9
attr dpt9test format g/m³ # gramm / m³
</syntaxhighlight>und schon steht die richtige Einheit dahinter... Oder Skalierung - Watt -> kW:<syntaxhighlight lang="text">
attr dpt9test stateCmd { return sprintf('%.3f kW',$state / 1000); }
</syntaxhighlight>Falsch definierte DPT's (z.B: dpt5 statt dpt7) produzieren falsche Ergebnisse, sowohl in FHEM als auch im KNX Device!

=== Übernehmen dieser Beispiele in die eigene config ===
Die meisten dieser Beispiele sind mittels "exportdevice <name>" erstellt. Bei der Übernahme mit c&p in die FHEM- commandozeile (oder auch Telnet) gibt's Fallstricke...(Es müssen Semicolons u. Zeilenumbrüche maskiert werden). Um das zu umgehen, schlage ich folgenden Vorgangsweise vor:

Definiere z.b. ein (kompliziertes) Attr stateCmd auf der FHEM-cmd Zeile:<syntaxhighlight lang="text">
attr meinDevice stateCmd {}
</syntaxhighlight>... also mit nichts drin! - Damit kann's auch keine syntax-Fehler geben! Danach geht man in den device-detail-View, klickt auf statecmd und mit c&p wird der code zwischen den (äussersten {} ) eingefügt. Selbes Vorgehen gilt auch für komplexe DevstateIcon, notifies, at,... Noch grössere code Teile sind sinnvoller in einer sub-routine in 99_myUtils.pm aufgehoben und werden z.b. im stateCmd aufgerufen:<syntaxhighlight lang="text">
attr <meinDevice> stateCmd { $state = meineAllerwichtigsteSubroutine(p1,p2,p3); }
</syntaxhighlight>Das hat dann auch den Vorteil, dass die sub-Routine von mehreren devices verwendet werden kann!
[[Kategorie:Examples]]
[[Kategorie:EIB/KNX]]
[[Kategorie:Gerätemodul]]