FHEMWiki - Benutzerbeiträge [de]

Hue

2024-07-30T19:23:16Z

Xaneu: /* HUE-Device */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge 192.168.0.123</code>
wird die Bridge eingebunden. (Die IP-Adresse gegen die der HUE Bridge ersetzen oder den DNS Namen.) Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*Paulmann Plug & Shine (an der Hue Bridge angelernt)
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.B. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

=== Spezielle Konfigurationsmöglichkeiten ===
Zur Syntax der nachfolgenden Attribute (für widgets) siehe {{Link2Forum|Topic=119298|LinkText=
Patchvorschlag im Forum}}
==== setList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''setsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=118788|LinkText=
Eurotonics Spirit bzw. MOES Thermostat}}
* [https://forum.fhem.de/index.php/topic,11020.msg1192888.html#msg1192888 HueLabs Scene aus FHEM über die HUEBridge ein- und ausschalten]

==== configList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''configsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=115102|Message=1093876|LinkText=Aqara motion sensor - duration}}
* {{Link2Forum|Topic=111887|Message=1064164|LinkText=Aqara vibration sensor - sensitivity}}
* [https://forum.fhem.de/index.php/topic,130869.msg1250786.html#msg1250786 Hue Bewegungsmelder - aktivieren, empfindlichkeit und mehr]

==== weiter Konfigurationsmöglichkeiten ====
Device spezifische Kommandos hinzufügen - [https://forum.fhem.de/index.php/topic,11020.msg1193583.html#msg1193583 effect] , [https://forum.fhem.de/index.php/topic,125676.msg1208041.html#msg1208041 startup]

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ in einer Proxmox-VM ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</syntaxhighlight>
:oder
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</syntaxhighlight>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<syntaxhighlight lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</syntaxhighlight>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<syntaxhighlight lang="bash">
qm set 804 -usb0 host=0403:6015
</syntaxhighlight>

* Installation von deCONZ:
:<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</syntaxhighlight>

=== Installation von deCONZ in einem Proxmox LXC-Container ===

[[Conbee/deCONZ im Proxmox LXC-Container (Tutorial)]]

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Entweder ihr installiert deCONZ direkt (wie hier beschrieben) oder über einen Docker Container. Der Docker Container hat ein paar Einschränkungen bzgl. Firmware Updates.

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<syntaxhighlight lang="bash">
sudo gpasswd -a pi dialout
</syntaxhighlight>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<syntaxhighlight lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</syntaxhighlight>

Mit der Einführung des Raspberry Pi 3 sind noch weitere Einstellungen notwendig. Diese sind hier: [[Raspberry Pi 3: GPIO-Port Module und Bluetooth|Raspberry Pi 3: GPIO-Port Module und Bluetooth – FHEMWiki]] ausführlich beschrieben.

deCONZ installieren:
:<syntaxhighlight lang="bash">
sudo apt install deconz
</syntaxhighlight>
Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<syntaxhighlight lang="bash">
systemctl enable deconz.service
</syntaxhighlight>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom lib-Verzeichnis nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Hue

2024-07-30T19:21:40Z

Xaneu: /* HUE-Device Paulmann Plug & Shine ergänzt */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge 192.168.0.123</code>
wird die Bridge eingebunden. (Die IP-Adresse gegen die der HUE Bridge ersetzen oder den DNS Namen.) Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*Paulmann Plug & Shine
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

Das HUEBridge Modul erkennt, wenn ein Leuchtmittel zwischen einer Hue und einer deCONZ Bridge (oder umgekehrt) wechselt und verschiebt das zugehörige HUEDevice in FHEM jeweils zum richtigen Bridge-Device. D.h. wenn z.B. zum Firmwareupdate die Bridge gewechselt wird, ist auf FHEM Seite nichts weiter zu tun.

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

=== Spezielle Konfigurationsmöglichkeiten ===
Zur Syntax der nachfolgenden Attribute (für widgets) siehe {{Link2Forum|Topic=119298|LinkText=
Patchvorschlag im Forum}}
==== setList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''setsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=118788|LinkText=
Eurotonics Spirit bzw. MOES Thermostat}}
* [https://forum.fhem.de/index.php/topic,11020.msg1192888.html#msg1192888 HueLabs Scene aus FHEM über die HUEBridge ein- und ausschalten]

==== configList ====
Ermöglicht einen indirekten Zugriff auf den Befehl ''configsensor'' der HUEBridge.

Beispiele
* {{Link2Forum|Topic=115102|Message=1093876|LinkText=Aqara motion sensor - duration}}
* {{Link2Forum|Topic=111887|Message=1064164|LinkText=Aqara vibration sensor - sensitivity}}
* [https://forum.fhem.de/index.php/topic,130869.msg1250786.html#msg1250786 Hue Bewegungsmelder - aktivieren, empfindlichkeit und mehr]

==== weiter Konfigurationsmöglichkeiten ====
Device spezifische Kommandos hinzufügen - [https://forum.fhem.de/index.php/topic,11020.msg1193583.html#msg1193583 effect] , [https://forum.fhem.de/index.php/topic,125676.msg1208041.html#msg1208041 startup]

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ in einer Proxmox-VM ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</syntaxhighlight>
:oder
:<syntaxhighlight lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</syntaxhighlight>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<syntaxhighlight lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</syntaxhighlight>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<syntaxhighlight lang="bash">
qm set 804 -usb0 host=0403:6015
</syntaxhighlight>

* Installation von deCONZ:
:<syntaxhighlight lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</syntaxhighlight>

=== Installation von deCONZ in einem Proxmox LXC-Container ===

[[Conbee/deCONZ im Proxmox LXC-Container (Tutorial)]]

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Entweder ihr installiert deCONZ direkt (wie hier beschrieben) oder über einen Docker Container. Der Docker Container hat ein paar Einschränkungen bzgl. Firmware Updates.

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<syntaxhighlight lang="bash">
sudo gpasswd -a pi dialout
</syntaxhighlight>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<syntaxhighlight lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</syntaxhighlight>

Mit der Einführung des Raspberry Pi 3 sind noch weitere Einstellungen notwendig. Diese sind hier: [[Raspberry Pi 3: GPIO-Port Module und Bluetooth|Raspberry Pi 3: GPIO-Port Module und Bluetooth – FHEMWiki]] ausführlich beschrieben.

deCONZ installieren:
:<syntaxhighlight lang="bash">
sudo apt install deconz
</syntaxhighlight>
Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<syntaxhighlight lang="bash">
systemctl enable deconz.service
</syntaxhighlight>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom lib-Verzeichnis nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Modul Shelly

2022-12-30T08:02:24Z

Xaneu: /* MQTT */

{{Infobox Modul
|ModPurpose=Das Modul 36_Shelly.pm stellt ein Interface zur Bedienung von Shelly Devices zur Verfügung
|ModType=d

|ModCmdRef=Shelly
|ModForumArea=Sonstige Systeme
|ModFTopic=118446
|ModTechName=36_Shelly.pm
|ModOwner=Prof. Dr. Peter A. Henning
}}
Auf dieser Seite werden die Aktoren des bulgarischen Herstellers Allterco Robotics beschrieben ((Markenname Shelly) sowie deren Ansteuerung mit FHEM und aufgetretene Probleme.
Für Supportanfragen bitte ''{{Link2Forum|Topic=118446.0|LinkText=diesen Forenthread}}'' verwenden.
{{Baustelle}}
'''Achtung: Diese Seite ist teilweise veraltet, insbesondere unterstützt das Modul weitere Aktoren. Bitte Commandref lesen - diese Seite ist in Überarbeitung'''

Es handelt sich um IP-basierte Schalt- und Dimmaktoren, die auf verschiedene Weise angesteuert werden können
*über die Web-Oberfläche des eingebauten Mikro-Webservers,
*über eine proprietäre App des Herstellers (Achtung, Cloud!),
*über das hier beschriebene FHEM-Modul 36_Shelly.pm
*über MQTT
Ein Teil der Aktoren verfügt über eine eingebaute Leistungsmessung.

== Geräteübersicht ==
{| class="wikitable mw-datatable"
! style="width:50px" |Modell
! style="width:50px" |Typ
! style="width:20px" |Schaltkanäle
! style="width:20px" |Dimmkanäle
! style="width:20px" |Messkanäle
! style="width:650px" |Bemerkungen
|-
|Shelly1
|Schalter
|1
|
|
|-
|Shelly1PM
|Schalter mit Leistungsmessung
|1
|
|1
|-
|ShellyPlug, ShellyPlugS
|Schalter mit Leistungsmessung
|1
|
|1
|-
|ShellyEM
|Leistungsmessung
|1
|
|2
|-
|Shelly2
|Schalter/Rollladenaktor
|2/1
|
|1
|-
|Shelly2.5
|Schalter/Rollladenaktor
|2/1
|
|2
|-
|Shelly4Pro
|Schalter
|4
|
|4
|-
|ShellyRGBW
|Dimmer
|
|4
|1
|-
|ShellyDimmer
|Dimmer
|
|1
|1
|}

== Einbindung in FHEM ==
*Schließen Sie den Aktor nach Vorschrift an
*Suchen Sie mit einem WLAN-fähigen Gerät (Laptop oder Smartphone) nach dem internen Access Point, der durch den Aktor erzeugt wird. Typischerweise hat dieser eine SSID ähnlich wie
shelly1-..., shellyswitch-..., shelly4pro-...,
*Verbinden Sie Ihr Gerät mit diesem Access Point. Typischerweise bekommt Ihr Gerät dabei die IP-Adresse 192.168.33.2 zugewiesen.
*Im Browser dieses Gerätes einfach die IP-Adresse 192.168.33.1 aufrufen - das ist der Shelly selbst, in dieser Web-Oberfläche kann man alles konfigurieren.
**Internen Access Point abschalten
**Shelly ins häusliche WLAN anmelden. Mit fester IP-Adresse <shelly-ip> natürlich...
**Testen: Ihr Gerät wieder mit dem häuslichen WLAN verbinden, und im Browser die Adresse <shelly-ip> aufrufen
*In FHEM definieren
define myShelly Shelly <shelly-ip>
*Auf der Detailseite des Devices muss unbedingt noch das Attribut <code>model</code> gesetzt werden:
attr myShelly model shellyrgbw|shellydimmer|shelly2.5|generic|shelly2|shellyem|shelly4|shellyplug|shelly1|shellybulb|shelly1pm|shellyuni
Falls es sich um einen Shelly2 oder 2.5 handelt, muss ferner das Attribut <code>mode</code> auf "roller" oder "relay" gesetzt werden. Mit diesem Modul können alle Daten übertragen und (prinzipiell) alle Konfigurationsänderungen durchgeführt werden, außerdem ist es auf einfachste Weise zu installieren. Das Modul pollt im per Attribut <code>interval</code> einstellbaren Abstand zyklisch den Aktor auf Statusänderungen (Wert 0 => kein Polling). Damit der Aktor im Stande ist, irgendwelche Zustandsänderungen ''von sich aus'' an FHEM zu melden, müssen diese als REST-Befehle (also URL-Aufrufe, für Nicht-Experten) in der Konfigurationsoberfläche des Shelly-Aktors eingetragen werden. Siehe CommandRef.

Zum Betrieb ist ferner noch zu bemerken, dass das Modul zwar meldet, ob ein Firmware-Update nötig ist - ausgelöst werden muss dieses aber über die Web-Oberfläche des Shelly selber.

=== MQTT ===
MQTT (Message Queue Telemetry Transport) ist ein nachrichtenbasiertes Protokoll, bei dem Geräte (Devices) nicht direkt miteinander, sondern mit einem zentralen MQTT-Server (in alter Nomenklatur ''Broker'' genannt) kommunizieren. Eine kurze Einführung in MQTT findet man auf der Seite [[MQTT Einführung]]. Mit entsprechend gesetzten Attributen lassen sich die Shelly-Aktoren auch steuern ([[MQTT2-Module - Praxisbeispiele#Shelly|Praxisbeispiele zu den MQTT2-Modulen]]), für Anfänger ist das allerdings nicht unbedingt zu empfehlen.

Modul Shelly

2022-12-30T07:54:12Z

Xaneu: /* MQTT */

{{Infobox Modul
|ModPurpose=Das Modul 36_Shelly.pm stellt ein Interface zur Bedienung von Shelly Devices zur Verfügung
|ModType=d

|ModCmdRef=Shelly
|ModForumArea=Sonstige Systeme
|ModFTopic=118446
|ModTechName=36_Shelly.pm
|ModOwner=Prof. Dr. Peter A. Henning
}}
Auf dieser Seite werden die Aktoren des bulgarischen Herstellers Allterco Robotics beschrieben ((Markenname Shelly) sowie deren Ansteuerung mit FHEM und aufgetretene Probleme.
Für Supportanfragen bitte ''{{Link2Forum|Topic=118446.0|LinkText=diesen Forenthread}}'' verwenden.
{{Baustelle}}
'''Achtung: Diese Seite ist teilweise veraltet, insbesondere unterstützt das Modul weitere Aktoren. Bitte Commandref lesen - diese Seite ist in Überarbeitung'''

Es handelt sich um IP-basierte Schalt- und Dimmaktoren, die auf verschiedene Weise angesteuert werden können
*über die Web-Oberfläche des eingebauten Mikro-Webservers,
*über eine proprietäre App des Herstellers (Achtung, Cloud!),
*über das hier beschriebene FHEM-Modul 36_Shelly.pm
*über MQTT
Ein Teil der Aktoren verfügt über eine eingebaute Leistungsmessung.

== Geräteübersicht ==
{| class="wikitable mw-datatable"
! style="width:50px" |Modell
! style="width:50px" |Typ
! style="width:20px" |Schaltkanäle
! style="width:20px" |Dimmkanäle
! style="width:20px" |Messkanäle
! style="width:650px" |Bemerkungen
|-
|Shelly1
|Schalter
|1
|
|
|-
|Shelly1PM
|Schalter mit Leistungsmessung
|1
|
|1
|-
|ShellyPlug, ShellyPlugS
|Schalter mit Leistungsmessung
|1
|
|1
|-
|ShellyEM
|Leistungsmessung
|1
|
|2
|-
|Shelly2
|Schalter/Rollladenaktor
|2/1
|
|1
|-
|Shelly2.5
|Schalter/Rollladenaktor
|2/1
|
|2
|-
|Shelly4Pro
|Schalter
|4
|
|4
|-
|ShellyRGBW
|Dimmer
|
|4
|1
|-
|ShellyDimmer
|Dimmer
|
|1
|1
|}

== Einbindung in FHEM ==
*Schließen Sie den Aktor nach Vorschrift an
*Suchen Sie mit einem WLAN-fähigen Gerät (Laptop oder Smartphone) nach dem internen Access Point, der durch den Aktor erzeugt wird. Typischerweise hat dieser eine SSID ähnlich wie
shelly1-..., shellyswitch-..., shelly4pro-...,
*Verbinden Sie Ihr Gerät mit diesem Access Point. Typischerweise bekommt Ihr Gerät dabei die IP-Adresse 192.168.33.2 zugewiesen.
*Im Browser dieses Gerätes einfach die IP-Adresse 192.168.33.1 aufrufen - das ist der Shelly selbst, in dieser Web-Oberfläche kann man alles konfigurieren.
**Internen Access Point abschalten
**Shelly ins häusliche WLAN anmelden. Mit fester IP-Adresse <shelly-ip> natürlich...
**Testen: Ihr Gerät wieder mit dem häuslichen WLAN verbinden, und im Browser die Adresse <shelly-ip> aufrufen
*In FHEM definieren
define myShelly Shelly <shelly-ip>
*Auf der Detailseite des Devices muss unbedingt noch das Attribut <code>model</code> gesetzt werden:
attr myShelly model shellyrgbw|shellydimmer|shelly2.5|generic|shelly2|shellyem|shelly4|shellyplug|shelly1|shellybulb|shelly1pm|shellyuni
Falls es sich um einen Shelly2 oder 2.5 handelt, muss ferner das Attribut <code>mode</code> auf "roller" oder "relay" gesetzt werden. Mit diesem Modul können alle Daten übertragen und (prinzipiell) alle Konfigurationsänderungen durchgeführt werden, außerdem ist es auf einfachste Weise zu installieren. Das Modul pollt im per Attribut <code>interval</code> einstellbaren Abstand zyklisch den Aktor auf Statusänderungen (Wert 0 => kein Polling). Damit der Aktor im Stande ist, irgendwelche Zustandsänderungen ''von sich aus'' an FHEM zu melden, müssen diese als REST-Befehle (also URL-Aufrufe, für Nicht-Experten) in der Konfigurationsoberfläche des Shelly-Aktors eingetragen werden. Siehe CommandRef.

Zum Betrieb ist ferner noch zu bemerken, dass das Modul zwar meldet, ob ein Firmware-Update nötig ist - ausgelöst werden muss dieses aber über die Web-Oberfläche des Shelly selber.

=== MQTT ===
MQTT (Message Queue Telemetry Transport) ist ein nachrichtenbasiertes Protokoll, bei dem Geräte (Devices) nicht direkt miteinander, sondern mit einem zentralen MQTT-Server (in alter Nomenklatur ''Broker'' genannt) kommunizieren. Eine kurze Einführung in MQTT findet man auf der Seite [[MQTT Einführung]]. Mit entsprechend gesetzten Attributen lassen sich die Shelly-Aktoren auch steuern ([[MQTT2-Module - Praxisbeispiele|Praxisbeispiele zu den MQTT2-Modulen]]), für Anfänger ist das allerdings nicht unbedingt zu empfehlen.

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-05-31T14:38:16Z

Xaneu: /* Weiterer Vorteil ergänzt */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung, Akku-Spannung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.
* Der Raspberry Pi kann vom FHEM-Server aus komplett (spannungslos) abgeschaltet werden.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang="pl">
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== PIUSV+ und Raspberry Pi 4 ==
Obwohl die PIUSV+ nur 2 A liefern kann, ist der Betrieb mit einem Raspberry Pi 4 durchaus möglich, sofern auf dem Raspberry hauptsächlich der FHEM-Server und keine sonstige hochperformante Software installiert ist.
Bei einer FHEM-Beispielinstallation (Raspian Buster, FHEM 6.0) mit USB-SSD-Platte (32GB), 3x USB/232-Konverter, einem Homematic-Sender/Empfängermodul (HM-MOD-PRI-PCB) und Nutzung der 1-Wire-, I²C- und 2xGPIO-Schnittstellen am 40pol. Pfostenverbinder beträgt der 5V-Versorgungsstrom ca. 0,9A (entspricht 4,5W).

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

DevelopmentModuleIntro

2020-04-22T07:07:15Z

Xaneu: Änderung wieder rückgängig gemacht, da das Verhalten unter IOS (IPAD) sich nicht geändert hat.

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

== Der Hash einer Geräteinstanz ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per <code>select()</code> überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion ([[#X_Ready|X_Ready]]) implementieren, welche prüft, ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt, beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert um die Daten zu interpretieren und Werte in Readings geschrieben.

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant. Durch eine Prüfung auf <code>$init_done</code> kann man erkennen, ob eine Definition von Hand (<code>$init_done</code> = 1) oder im Rahmen der Initialisierung (FHEM Start / Rereadcfg => <code>$init_done</code> = 0) erfolgte. Während der Initialisierung stehen bspw. die gesetzten Attribute der Definition noch nicht zur Verfügung und können daher nicht ausgewertet werden (siehe .
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL}</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''ELEMENT}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via [[DevIo]]), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen, je nach Hardwareperformance, spürbare Last auf dem System (siehe [[DevelopmentModuleIntro#X_Notify|NotifyFn]]), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird für die Modulprogrammierung die Funktion <code>[[DevelopmentModuleAPI#readingsDelete|readingsDelete()]]</code> empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>
{{Hinweis|'''Hintergrundinfo dazu aus dem Forum:''' {{Link2Forum|Topic=83069|Message=753066}}

<code>CommandDeleteReading()</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wenn der Modulautor beim Aufruf auch <code>$cl</code> weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.
}}

== Events ==

FHEM verfügt über einen Event-Mechanismus um Änderungen verschiedenster Art an einzelne oder alle Definitionen mitzuteilen. Jedes Modul (und damit alle Definitionen dieses Moduls) können auf Events von FHEM selber (Definition <code>global</code>) oder von anderen Definitionen reagieren und dadurch selber aktiv werden. Ein Event wird innerhalb von FHEM als Zeichenkette behandelt.

Events sind grundsätzlich immer definitionsbezogen. Das bedeutet, dass ein Event immer in Verbindung mit einem Definitionsnamen erzeugt wird. Jede Definition, welche ein Event verarbeitet, erhält den Definitions-Hash (<code>$hash</code>) der auslösenden Definition.

Events werden typischerweise bei der Erstellung von Readings implizit für jedes einzelne Reading erzeugt. Es gibt jedoch auch Events die nichts mit Readings zu tun haben um anderweitige Änderungen bekannt zu geben.

Eigene Events können in FHEM mit der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] erzeugt werden. Um auf Events in einem Modul reagieren zu können, muss eine [[#X_Notify|Notify]]-Funktion implementiert sein. Sobald ein oder mehrere Events für eine Definition getriggert werden, prüft FHEM, welche Definitionen über Events der auslösenden Definition informiert werden möchten. Diese werden dann nacheinander in einer bestimmten Reihenfolge durch Aufruf der [[#X_Notify|Notify]]-Funktion über anstehende Events in Kenntnis gesetzt. Es obliegt dann dem jeweiligen Modul, wie es auf die Events reagiert.

=== globale Events ===

Als "globale Events" werden alle Events bezeichnet, die durch die Definition <code>global</code> erzeugt werden. Es handelt sich hierbei um Events die Strukturänderungen in der Konfiguration, als auch systemweite Ereignisse zu FHEM selbst signalisieren.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>INITIALIZED</code>''' || Der Start von FHEM ist abgeschlossen. Sämtliche Definitionen und Attribute wurden aus der Konfiguration (fhem.cfg oder configDB) eingelesen, sowie sämtliche Readings sind aus dem State-File eingelesen und stehen nun voll umfänglich zur Verfügung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>REREADCFG</code>''' || Die Konfiguration wurde erneut eingelesen. Dies bedeutet, es wurden alle Definitionen/Attribute/Readings aus FHEM entfernt und durch Einlesen der Konfiguration neu angelegt. (FHEM-Befehl: "rereadcfg")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SAVE</code>''' || Die laufende Konfiguration soll gespeichert werden (in fhem.cfg oder configDB). Dieses Event wird '''VOR''' dem Speichern der Konfiguration getriggert. Sobald der Trigger verarbeitet wurde, beginnt das Speichern der Konfiguration. (FHEM-Befehl: "save")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DEFINED ''<Name>''</code>''' || Es wurde eine neue Definition mit Namen <code>''<Name>''</code> angelegt. (FHEM-Befehl: "define")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DELETED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde gelöscht. (FHEM-Befehl: "delete")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>RENAMED ''<Alt>'' ''<Neu>''</code>''' || Die Definition mit dem Namen <code>''<Alt>''</code> wurde in den Namen <code>''<Neu>''</code> umbenannt. (FHEM-Befehl: "rename")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UNDEFINED ''<Name> <Modul> <Define-Parameter>''</code>''' || Es wurde eine Nachricht von einem physikalischen Modul (siehe [[#Zweistufiges Modell für Module|zweistufiges Modulkonzept]]) erhalten, für die keine passende logische Definition in FHEM existiert. Details dazu, siehe dazu Abschnitt [[#Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)|Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)]].
|}

=== Begrenzung von Events ===

Ein Modul, welches Events verarbeitet, kann die Eventverarbeitung auf bestimmte Definitionen begrenzen. Dadurch werden nur Events an das Modul gemeldet (via [[#X_Notify|X_Notify()]]), welche von einer oder mehreren bestimmten Definitionen getriggert wurden. Dadurch werden unnötige Events nicht an das Modul gemeldet und schont somit Ressourcen.

Standardmäßig werden sämtliche Events ohne Begrenzung an ein Modul gemeldet, welches eine [[#X_Notify|Notify]]-Funktion implementiert hat und somit Events verarbeiten kann. Details zur Begrenzung von Events findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

=== Reihenfolge der Eventverarbeitung ===

Ein getriggertes Event wird nacheinander gegen jede Definition geprüft, deren Modul eine [[#X_Notify|Notify]]-Funktion implementiert hat. Dies bedeutet, jede Definition wird nacheinander durch Aufruf der [[#X_Notify|Notify]]-Funktion mit dem Definitionshash der auslösenden Definition aufgerufen.

Unter bestimmten Umständen kann es erforderlich sein, in diese Reihenfolge einzugreifen. Beispielsweise wenn das eigene Modul und deren Definitionen das Event als letztes oder erstes verarbeiten müssen. Ein Beispiel bietet hierbei das Modul [[dewpoint]], welches Events vor allen anderen Modulen verarbeiten muss.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</syntaxhighlight>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von fhem.pl nach dem Laden des Moduls aufgerufen und bekommt eine leere Hashreferenz für den Initialisierungsvorgang übergeben.

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<syntaxhighlight lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
$hash->{DelayedShutdownFn} = "X_ DelayedShutdown";
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu {{Link2CmdRef|Anker=readingFnAttributes|Label=readingFnAttributes}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Define-Funktion eines Moduls wird von FHEM aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.) oder einen [[#Pollen_von_Geräten|Status-Timer]] zu starten.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

Verfügbarkeit von Attributen

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams()]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams() automatisch aufgerufen und X_Define() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
Die Undef-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls <code>rereadcfg</code>, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu einliest. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern, sofern diese im Modul zum Pollen verwendet wurden (siehe Abschnitt [[#Pollen_von_Geräten|Pollen von Geräten]]).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> für eine Definition dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$opt</code> plus optional weiterer Parameter <code>@args</code> übergeben. Als Rückgabewert <code>$result</code> wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>get ''<NAME>'' '''?'''</code>, welche durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert direkt abfragen und diesen als Return-Wert der Get-Funktion zurückgeben. Vielfach werden aber auch die vorhandenen Readings zurückgegeben.

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Get() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$cmd</code> und optional weitere Argumente <code>@args</code> übergeben. Als Rückgabewert <code>$error</code> kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert.

Standardmäßig wird jeder Set-Befehl, welcher erfolgreich ausgeführt wurde (<code>$error</code> ist <code>undef</code>), als Event getriggert um dies bspw. in einem FileLog festzuhalten. Dieses Verhalten kann optional unterbunden werden indem der optionale zweite Rückgabewert <code>$skip_trigger</code> auf <code>1</code> gesetzt wird. Damit wird das Generieren eines Events für das erfolgreich ausgeführte Set-Kommando unterbunden. Falls nicht gesetzt, wird ein Event erzeugt (<code>$cmd</code> mit sämtlichen <code>@args</code>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen der Ausführung eines getriggerten [[Notify]] auftreten, werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zu Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter (<code>@args</code>) übergeben um Zustände zu setzen/ändern.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>set ''<NAME>'' '''?'''</code>, welcher durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Nutzung von SetExtensions.pm

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Set() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.
|-
| '''slider''',<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.
|-
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| Es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Die genaue Parametersyntax kann man dem Artikel zum [[Color#Colorpicker|Colorpicker]] entnehmen.
|-
| '''multiple''' || <code>group:multiple,Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt.
|-
| '''sortable''' || <code>command:sortable,monday,tuesday,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</syntaxhighlight>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in FHEMWEB durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Serial-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion [[DevIo#DevIo_SimpleRead()|DevIo_SimpleRead()]] gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern (siehe auch [[DevIo#Hinweis bei der Datenverarbeitung (Buffering)|DevIo]]). Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat, je nachdem auf welchem OS FHEM ausgeführt wird, unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls [[DevIo]] wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das {{Link2CmdRef|Anker=addStateEvent|Lang=de|Label=addStateEvent-Attribut}} vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer {{Link2CmdRef|Lang=de|Anker=devspec|Label=devspec}} in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der gewünschten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion registriert sein. Diese dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein - je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das Aktivieren des inform-Mechanismus zum Senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Funktion X_AsyncOutput wird durch [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] von anderen Modulen aufgerufen. Es erlaubt diesen anderen Modulen die Ausgabe von asynchronen Befehlsergebnissen <code>$text</code> zuvor ausgeführter set-/get-Befehle an den entsprechenden Client (identifiziert durch den Client-Hash <code>$client_hash</code> der temporären Definition) zurückzugeben.

Wenn ein Client einen set-/get-Befehl ausführt, wird der Client-Hash bei der Ausführung dieser Befehle an die jeweiligen Module übermittelt. Sobald ein Befehl ausgeführt wird, der seine Ausgabe asynchron ausführen möchte und die Client-Verbindung des Server-Moduls dies unterstützt (<code>$client_hash->{canAsyncOutput}</code> ist gesetzt), merkt sich das befehlsausführende Modul den Client-Hash und gibt das Ergebnis des Befehls zu späterer Zeit via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an den ursprünglichen Client zurück. Die Funktion X_AsyncOutput des Server-Moduls kümmert sich darum das Ergebnis dem entsprechenden Client in der notwendigen Form zuzustellen.

Der Rückgabewert von X_AsyncOutput() wird als Rückgabewert für asyncOutput() verwendet. Man kann hier im Fehlerfall eine Fehlermeldung angeben und im Erfolgsfall <code>undef</code>. Der Rückgabewert wird aber aktuell nicht ausgewertet.

==== X_ActivateInform====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

Die Funktion X_ActivateInform wird aktuell nur durch den [[update]]-Befehl aufgerufen, sofern ein Client eines Frontend-Moduls diesen Befehl aufgerufen hat um den Inform-Mechanismus (Senden von Events) zu aktivieren. Dadurch wird im Falle von [[update]] die umgehende Anzeige der Logmeldungen für den ausführenden Client aktiviert. In [[FHEMWEB]] geschieht das über den Event-Monitor, bei telnet mit der direkten Ausgabe.

Da diese Funktion aktuell nur speziell für den update-Befehl implementiert ist, kann man aktuell keine genaue Angaben zu den möglichen Werten von <code>$arg</code> geben. Dieser Parameter dient dazu genauer zu spezifizieren was exakt an Events an den entsprechenden Client <code>$client_hash</code> zu senden ist. Aktuell wird dazu die Parametersyntax des inform-Befehls verwendet (on|off|log|raw|timer|status).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan="2" align="center" | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben, der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

Die Authorize-Funktion wird von fhem.pl aufgerufen um zu erfragen, ob ein bestimmter Client <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf. Auf diese Weise können Module Einfluss nehmen, welcher User welche Funktionen in FHEM nutzen darf. Wenn ein Client eine Aktion ausführen möchte, werden alle Module, die eine Authorize-Funktion implementiert haben, gefragt, ob diese Aktion ausgeführt werden darf. Als Rückgabewert wird das Ergebnis der Überprüfung zurückgegeben, wobei <code>0</code> (unbekannt / nicht zuständig), <code>1</code> (erlaubt) oder <code>2</code> (verboten) zurückgegeben werden können.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
| rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| style="white-space: nowrap;" | <code>'''$arg''' = "set Lampe on"</code> || Jeglicher FHEM-Befehl, der ausgeführt werden soll, wird in <code>$arg</code> hinterlegt, sodass innerhalb einer Authorize-Funktion der Befehl genauer geparst werden kann um zu entscheiden, ob dieser Befehl erlaubt ist, oder nicht.
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "perl"</code> || Ausführen von Perl-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "shell"</code> || Ausführen von Shell-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
| style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
| style="white-space: nowrap;" | <code>'''$arg''' = "Licht_Wohnzimmer"</code> || Sichtbarkeit des jeweiligen Gerät/Definition in FHEM. Dies bedeutet konkret die Auffindbarkeit im <code>list</code>-Befehl, sowie der Suche via [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wird eine solche Anfrage durch die Authorize-Funktion abgelehnt, ist das entsprechende Gerät bzw. Definition für den jeweiligen Client nicht sichtbar.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> (regulärer Ausdruck für Modulnamen) die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

Um für eine einzelne Geräteinstanz das Verbose-Level zu erhöhen, ohne gleich für das gesamte FHEM den globalen Verbose-Level zu erhöhen und damit alle Meldungen zu erzeugen, kann man den Befehl
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der {{Link2CmdRef|Lang=de|Anker=verbose}} beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. Die Match-Liste enthält eine Liste von regulären Ausdrücken und ordnet diese einem Modul zu. Wenn eine Nachricht auf einen solchen regulären Ausdruck passt und das Modul noch nicht geladen ist, lädt FHEM dieses automatisch nach, zwecks Verarbeitung der Nachricht.

Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] (Auflistung von logischen Modulen) kann FHEM feststellen, welche logischen Module mit dem physischen Modul kommunizieren können. Nur die hier aufgelisteten, logischen Module werden beim Aufruf von [[DevelopmentModuleAPI#Dispatch|Dispatch()]] angesprochen.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten in beliebiger Form an die Hardware übertragen können.

logisches Modul

Das logische Modul interpretiert die via Dispatch() übergebene Nachricht (Zeichenkette) durch eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] (regulärer Ausdruck) zur Verfügung anhand [[DevelopmentModuleAPI#Dispatch|Dispatch()]] ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann. Nur Nachrichten, welche auf diesen Ausdruck passen, werden an das logische Modul weitergegeben (Aufruf [[#X_Parse|Parse]]-Funktion).

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welchen logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen (z.B. <code>CUL_.*</code> um die logischen Module CUL_HM, CUL_MAX, etc. zu verwenden).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:<syntaxhighlight>
FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT
</syntaxhighlight>Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können (Prüfung via [[#Der Match-Ausdruck|Match-Ausdruck]])
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</syntaxhighlight>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann ([[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur alle bisher geladenen Module aus der [[#Die Client-Liste|Client-Liste]]), so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</code>) dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird die Match-Liste mittels sort() nach dem Schlüssel (Sortierpräfix + Modulname) sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern zeichenbasierend.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion des eigenen Moduls aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition des physischen Moduls öffnet eine Verbindung zur Hardware (z.B. via [[DevIo]]). Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() prüft alle geladenen Module aus der [[#Die_Client-Liste|Client-Liste]] des physikalischen Moduls nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem logischen Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig nach Abschluss der Parse-Funktion.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt. Sollte der Fingerprint einer Nachricht innerhalb einer bestimmten Zeit (globales Attribut <code>dupTimeout</code>, standardmäßig 500ms) bereits empfangen worden sein, so wird die Nachricht verworfen. Dies ist insbesondere bei funkbasierter Hardware notwendig, wenn mehrere Empfänger die selbe Nachricht empfangen.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| style="vertical-align:top; white-space: nowrap;" | <code>ATTR</code>|| style="vertical-align:top; white-space: nowrap;" | <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| style="vertical-align:top; white-space: nowrap;" | <code>FILTER</code> || style="vertical-align:top; white-space: nowrap;" | <code>"%NAME"</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| style="vertical-align:top; white-space: nowrap;" | <code>GPLOT</code> || style="vertical-align:top; white-space: nowrap;" | <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| style="vertical-align:top; white-space: nowrap;" | <code>autocreateThreshold</code> || style="vertical-align:top; white-space: nowrap;" | <code>"2:10"</code> || Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| style="vertical-align:top; white-space: nowrap;" | <code>noAutocreatedFilelog</code>|| style="vertical-align:top; white-space: nowrap;" | <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM {{Link2CmdRef}} sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a name="Hellodefine"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a name="Helloset"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a name="Helloget"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a name="Helloattr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]

[[Kategorie:Development]]

DevelopmentModuleIntro

2020-04-22T07:02:27Z

Xaneu: /* Die Client-Liste */

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

== Der Hash einer Geräteinstanz ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per <code>select()</code> überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion ([[#X_Ready|X_Ready]]) implementieren, welche prüft, ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt, beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert um die Daten zu interpretieren und Werte in Readings geschrieben.

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant. Durch eine Prüfung auf <code>$init_done</code> kann man erkennen, ob eine Definition von Hand (<code>$init_done</code> = 1) oder im Rahmen der Initialisierung (FHEM Start / Rereadcfg => <code>$init_done</code> = 0) erfolgte. Während der Initialisierung stehen bspw. die gesetzten Attribute der Definition noch nicht zur Verfügung und können daher nicht ausgewertet werden (siehe .
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL}</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''ELEMENT}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via [[DevIo]]), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen, je nach Hardwareperformance, spürbare Last auf dem System (siehe [[DevelopmentModuleIntro#X_Notify|NotifyFn]]), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird für die Modulprogrammierung die Funktion <code>[[DevelopmentModuleAPI#readingsDelete|readingsDelete()]]</code> empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>
{{Hinweis|'''Hintergrundinfo dazu aus dem Forum:''' {{Link2Forum|Topic=83069|Message=753066}}

<code>CommandDeleteReading()</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wenn der Modulautor beim Aufruf auch <code>$cl</code> weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.
}}

== Events ==

FHEM verfügt über einen Event-Mechanismus um Änderungen verschiedenster Art an einzelne oder alle Definitionen mitzuteilen. Jedes Modul (und damit alle Definitionen dieses Moduls) können auf Events von FHEM selber (Definition <code>global</code>) oder von anderen Definitionen reagieren und dadurch selber aktiv werden. Ein Event wird innerhalb von FHEM als Zeichenkette behandelt.

Events sind grundsätzlich immer definitionsbezogen. Das bedeutet, dass ein Event immer in Verbindung mit einem Definitionsnamen erzeugt wird. Jede Definition, welche ein Event verarbeitet, erhält den Definitions-Hash (<code>$hash</code>) der auslösenden Definition.

Events werden typischerweise bei der Erstellung von Readings implizit für jedes einzelne Reading erzeugt. Es gibt jedoch auch Events die nichts mit Readings zu tun haben um anderweitige Änderungen bekannt zu geben.

Eigene Events können in FHEM mit der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] erzeugt werden. Um auf Events in einem Modul reagieren zu können, muss eine [[#X_Notify|Notify]]-Funktion implementiert sein. Sobald ein oder mehrere Events für eine Definition getriggert werden, prüft FHEM, welche Definitionen über Events der auslösenden Definition informiert werden möchten. Diese werden dann nacheinander in einer bestimmten Reihenfolge durch Aufruf der [[#X_Notify|Notify]]-Funktion über anstehende Events in Kenntnis gesetzt. Es obliegt dann dem jeweiligen Modul, wie es auf die Events reagiert.

=== globale Events ===

Als "globale Events" werden alle Events bezeichnet, die durch die Definition <code>global</code> erzeugt werden. Es handelt sich hierbei um Events die Strukturänderungen in der Konfiguration, als auch systemweite Ereignisse zu FHEM selbst signalisieren.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>INITIALIZED</code>''' || Der Start von FHEM ist abgeschlossen. Sämtliche Definitionen und Attribute wurden aus der Konfiguration (fhem.cfg oder configDB) eingelesen, sowie sämtliche Readings sind aus dem State-File eingelesen und stehen nun voll umfänglich zur Verfügung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>REREADCFG</code>''' || Die Konfiguration wurde erneut eingelesen. Dies bedeutet, es wurden alle Definitionen/Attribute/Readings aus FHEM entfernt und durch Einlesen der Konfiguration neu angelegt. (FHEM-Befehl: "rereadcfg")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SAVE</code>''' || Die laufende Konfiguration soll gespeichert werden (in fhem.cfg oder configDB). Dieses Event wird '''VOR''' dem Speichern der Konfiguration getriggert. Sobald der Trigger verarbeitet wurde, beginnt das Speichern der Konfiguration. (FHEM-Befehl: "save")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DEFINED ''<Name>''</code>''' || Es wurde eine neue Definition mit Namen <code>''<Name>''</code> angelegt. (FHEM-Befehl: "define")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DELETED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde gelöscht. (FHEM-Befehl: "delete")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>RENAMED ''<Alt>'' ''<Neu>''</code>''' || Die Definition mit dem Namen <code>''<Alt>''</code> wurde in den Namen <code>''<Neu>''</code> umbenannt. (FHEM-Befehl: "rename")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UNDEFINED ''<Name> <Modul> <Define-Parameter>''</code>''' || Es wurde eine Nachricht von einem physikalischen Modul (siehe [[#Zweistufiges Modell für Module|zweistufiges Modulkonzept]]) erhalten, für die keine passende logische Definition in FHEM existiert. Details dazu, siehe dazu Abschnitt [[#Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)|Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)]].
|}

=== Begrenzung von Events ===

Ein Modul, welches Events verarbeitet, kann die Eventverarbeitung auf bestimmte Definitionen begrenzen. Dadurch werden nur Events an das Modul gemeldet (via [[#X_Notify|X_Notify()]]), welche von einer oder mehreren bestimmten Definitionen getriggert wurden. Dadurch werden unnötige Events nicht an das Modul gemeldet und schont somit Ressourcen.

Standardmäßig werden sämtliche Events ohne Begrenzung an ein Modul gemeldet, welches eine [[#X_Notify|Notify]]-Funktion implementiert hat und somit Events verarbeiten kann. Details zur Begrenzung von Events findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

=== Reihenfolge der Eventverarbeitung ===

Ein getriggertes Event wird nacheinander gegen jede Definition geprüft, deren Modul eine [[#X_Notify|Notify]]-Funktion implementiert hat. Dies bedeutet, jede Definition wird nacheinander durch Aufruf der [[#X_Notify|Notify]]-Funktion mit dem Definitionshash der auslösenden Definition aufgerufen.

Unter bestimmten Umständen kann es erforderlich sein, in diese Reihenfolge einzugreifen. Beispielsweise wenn das eigene Modul und deren Definitionen das Event als letztes oder erstes verarbeiten müssen. Ein Beispiel bietet hierbei das Modul [[dewpoint]], welches Events vor allen anderen Modulen verarbeiten muss.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</syntaxhighlight>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von fhem.pl nach dem Laden des Moduls aufgerufen und bekommt eine leere Hashreferenz für den Initialisierungsvorgang übergeben.

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<syntaxhighlight lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
$hash->{DelayedShutdownFn} = "X_ DelayedShutdown";
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu {{Link2CmdRef|Anker=readingFnAttributes|Label=readingFnAttributes}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Define-Funktion eines Moduls wird von FHEM aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.) oder einen [[#Pollen_von_Geräten|Status-Timer]] zu starten.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

Verfügbarkeit von Attributen

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams()]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams() automatisch aufgerufen und X_Define() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
Die Undef-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls <code>rereadcfg</code>, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu einliest. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern, sofern diese im Modul zum Pollen verwendet wurden (siehe Abschnitt [[#Pollen_von_Geräten|Pollen von Geräten]]).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> für eine Definition dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$opt</code> plus optional weiterer Parameter <code>@args</code> übergeben. Als Rückgabewert <code>$result</code> wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>get ''<NAME>'' '''?'''</code>, welche durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert direkt abfragen und diesen als Return-Wert der Get-Funktion zurückgeben. Vielfach werden aber auch die vorhandenen Readings zurückgegeben.

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Get() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$cmd</code> und optional weitere Argumente <code>@args</code> übergeben. Als Rückgabewert <code>$error</code> kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert.

Standardmäßig wird jeder Set-Befehl, welcher erfolgreich ausgeführt wurde (<code>$error</code> ist <code>undef</code>), als Event getriggert um dies bspw. in einem FileLog festzuhalten. Dieses Verhalten kann optional unterbunden werden indem der optionale zweite Rückgabewert <code>$skip_trigger</code> auf <code>1</code> gesetzt wird. Damit wird das Generieren eines Events für das erfolgreich ausgeführte Set-Kommando unterbunden. Falls nicht gesetzt, wird ein Event erzeugt (<code>$cmd</code> mit sämtlichen <code>@args</code>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen der Ausführung eines getriggerten [[Notify]] auftreten, werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zu Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter (<code>@args</code>) übergeben um Zustände zu setzen/ändern.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>set ''<NAME>'' '''?'''</code>, welcher durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Nutzung von SetExtensions.pm

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Set() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.
|-
| '''slider''',<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.
|-
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| Es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Die genaue Parametersyntax kann man dem Artikel zum [[Color#Colorpicker|Colorpicker]] entnehmen.
|-
| '''multiple''' || <code>group:multiple,Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt.
|-
| '''sortable''' || <code>command:sortable,monday,tuesday,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</syntaxhighlight>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in FHEMWEB durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Serial-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion [[DevIo#DevIo_SimpleRead()|DevIo_SimpleRead()]] gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern (siehe auch [[DevIo#Hinweis bei der Datenverarbeitung (Buffering)|DevIo]]). Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat, je nachdem auf welchem OS FHEM ausgeführt wird, unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls [[DevIo]] wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das {{Link2CmdRef|Anker=addStateEvent|Lang=de|Label=addStateEvent-Attribut}} vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer {{Link2CmdRef|Lang=de|Anker=devspec|Label=devspec}} in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der gewünschten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion registriert sein. Diese dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein - je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das Aktivieren des inform-Mechanismus zum Senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Funktion X_AsyncOutput wird durch [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] von anderen Modulen aufgerufen. Es erlaubt diesen anderen Modulen die Ausgabe von asynchronen Befehlsergebnissen <code>$text</code> zuvor ausgeführter set-/get-Befehle an den entsprechenden Client (identifiziert durch den Client-Hash <code>$client_hash</code> der temporären Definition) zurückzugeben.

Wenn ein Client einen set-/get-Befehl ausführt, wird der Client-Hash bei der Ausführung dieser Befehle an die jeweiligen Module übermittelt. Sobald ein Befehl ausgeführt wird, der seine Ausgabe asynchron ausführen möchte und die Client-Verbindung des Server-Moduls dies unterstützt (<code>$client_hash->{canAsyncOutput}</code> ist gesetzt), merkt sich das befehlsausführende Modul den Client-Hash und gibt das Ergebnis des Befehls zu späterer Zeit via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an den ursprünglichen Client zurück. Die Funktion X_AsyncOutput des Server-Moduls kümmert sich darum das Ergebnis dem entsprechenden Client in der notwendigen Form zuzustellen.

Der Rückgabewert von X_AsyncOutput() wird als Rückgabewert für asyncOutput() verwendet. Man kann hier im Fehlerfall eine Fehlermeldung angeben und im Erfolgsfall <code>undef</code>. Der Rückgabewert wird aber aktuell nicht ausgewertet.

==== X_ActivateInform====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

Die Funktion X_ActivateInform wird aktuell nur durch den [[update]]-Befehl aufgerufen, sofern ein Client eines Frontend-Moduls diesen Befehl aufgerufen hat um den Inform-Mechanismus (Senden von Events) zu aktivieren. Dadurch wird im Falle von [[update]] die umgehende Anzeige der Logmeldungen für den ausführenden Client aktiviert. In [[FHEMWEB]] geschieht das über den Event-Monitor, bei telnet mit der direkten Ausgabe.

Da diese Funktion aktuell nur speziell für den update-Befehl implementiert ist, kann man aktuell keine genaue Angaben zu den möglichen Werten von <code>$arg</code> geben. Dieser Parameter dient dazu genauer zu spezifizieren was exakt an Events an den entsprechenden Client <code>$client_hash</code> zu senden ist. Aktuell wird dazu die Parametersyntax des inform-Befehls verwendet (on|off|log|raw|timer|status).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan="2" align="center" | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben, der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

Die Authorize-Funktion wird von fhem.pl aufgerufen um zu erfragen, ob ein bestimmter Client <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf. Auf diese Weise können Module Einfluss nehmen, welcher User welche Funktionen in FHEM nutzen darf. Wenn ein Client eine Aktion ausführen möchte, werden alle Module, die eine Authorize-Funktion implementiert haben, gefragt, ob diese Aktion ausgeführt werden darf. Als Rückgabewert wird das Ergebnis der Überprüfung zurückgegeben, wobei <code>0</code> (unbekannt / nicht zuständig), <code>1</code> (erlaubt) oder <code>2</code> (verboten) zurückgegeben werden können.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
| rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| style="white-space: nowrap;" | <code>'''$arg''' = "set Lampe on"</code> || Jeglicher FHEM-Befehl, der ausgeführt werden soll, wird in <code>$arg</code> hinterlegt, sodass innerhalb einer Authorize-Funktion der Befehl genauer geparst werden kann um zu entscheiden, ob dieser Befehl erlaubt ist, oder nicht.
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "perl"</code> || Ausführen von Perl-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "shell"</code> || Ausführen von Shell-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
| style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
| style="white-space: nowrap;" | <code>'''$arg''' = "Licht_Wohnzimmer"</code> || Sichtbarkeit des jeweiligen Gerät/Definition in FHEM. Dies bedeutet konkret die Auffindbarkeit im <code>list</code>-Befehl, sowie der Suche via [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wird eine solche Anfrage durch die Authorize-Funktion abgelehnt, ist das entsprechende Gerät bzw. Definition für den jeweiligen Client nicht sichtbar.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> (regulärer Ausdruck für Modulnamen) die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

Um für eine einzelne Geräteinstanz das Verbose-Level zu erhöhen, ohne gleich für das gesamte FHEM den globalen Verbose-Level zu erhöhen und damit alle Meldungen zu erzeugen, kann man den Befehl
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der {{Link2CmdRef|Lang=de|Anker=verbose}} beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. Die Match-Liste enthält eine Liste von regulären Ausdrücken und ordnet diese einem Modul zu. Wenn eine Nachricht auf einen solchen regulären Ausdruck passt und das Modul noch nicht geladen ist, lädt FHEM dieses automatisch nach, zwecks Verarbeitung der Nachricht.

Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] (Auflistung von logischen Modulen) kann FHEM feststellen, welche logischen Module mit dem physischen Modul kommunizieren können. Nur die hier aufgelisteten, logischen Module werden beim Aufruf von [[DevelopmentModuleAPI#Dispatch|Dispatch()]] angesprochen.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten in beliebiger Form an die Hardware übertragen können.

logisches Modul

Das logische Modul interpretiert die via Dispatch() übergebene Nachricht (Zeichenkette) durch eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] (regulärer Ausdruck) zur Verfügung anhand [[DevelopmentModuleAPI#Dispatch|Dispatch()]] ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann. Nur Nachrichten, welche auf diesen Ausdruck passen, werden an das logische Modul weitergegeben (Aufruf [[#X_Parse|Parse]]-Funktion).

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welchen logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen (z.B. <code>CUL_.*</code> um die logischen Module CUL_HM, CUL_MAX, etc. zu verwenden).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:

<text>FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT</text>

Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können (Prüfung via [[#Der Match-Ausdruck|Match-Ausdruck]])
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</syntaxhighlight>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann ([[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur alle bisher geladenen Module aus der [[#Die Client-Liste|Client-Liste]]), so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</code>) dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird die Match-Liste mittels sort() nach dem Schlüssel (Sortierpräfix + Modulname) sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern zeichenbasierend.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion des eigenen Moduls aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition des physischen Moduls öffnet eine Verbindung zur Hardware (z.B. via [[DevIo]]). Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() prüft alle geladenen Module aus der [[#Die_Client-Liste|Client-Liste]] des physikalischen Moduls nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem logischen Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig nach Abschluss der Parse-Funktion.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt. Sollte der Fingerprint einer Nachricht innerhalb einer bestimmten Zeit (globales Attribut <code>dupTimeout</code>, standardmäßig 500ms) bereits empfangen worden sein, so wird die Nachricht verworfen. Dies ist insbesondere bei funkbasierter Hardware notwendig, wenn mehrere Empfänger die selbe Nachricht empfangen.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| style="vertical-align:top; white-space: nowrap;" | <code>ATTR</code>|| style="vertical-align:top; white-space: nowrap;" | <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| style="vertical-align:top; white-space: nowrap;" | <code>FILTER</code> || style="vertical-align:top; white-space: nowrap;" | <code>"%NAME"</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| style="vertical-align:top; white-space: nowrap;" | <code>GPLOT</code> || style="vertical-align:top; white-space: nowrap;" | <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| style="vertical-align:top; white-space: nowrap;" | <code>autocreateThreshold</code> || style="vertical-align:top; white-space: nowrap;" | <code>"2:10"</code> || Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| style="vertical-align:top; white-space: nowrap;" | <code>noAutocreatedFilelog</code>|| style="vertical-align:top; white-space: nowrap;" | <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM {{Link2CmdRef}} sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a name="Hellodefine"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a name="Helloset"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a name="Helloget"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a name="Helloattr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]

[[Kategorie:Development]]

DevelopmentModuleIntro

2020-04-22T06:55:12Z

Xaneu: Die Client-Liste (Beispiel) anstatt als Computer-Code jetzt als Tabelle dargestellt, da die Liste unter IOS (IPAD) offensichtlich als Steuercode interpretiert wird und deswegen die gesamte Seite ständig neu geladen wird.

{{Hinweis|Dieser Text ist in Arbeit und muss noch an einigen Stellen ergänzt werden. }}

== Einleitung ==

Um neue Geräte, Dienste, o.ä. in FHEM verfügbar zu machen, kann man ein eigenes Modul in Perl schreiben. Ein Modul wird in FHEM automatisch geladen, wenn ein entsprechendes Device in FHEM definiert wird. Das Modul ermöglicht eine spezifische Kommunikation mit einem physikalischen Gerät, stellt Ergebnisse ("Readings") und Events innerhalb von FHEM zur Verfügung und erlaubt es, das Gerät mit "Set"-/"Get"-Befehlen zu beeinflussen. Dieser Artikel soll den Einstieg in die Entwicklung eigener Module erleichtern.

Mit dem FHEM-Befehl <code>define</code> werden Devices in FHEM basierend auf einem Modul definiert. Dieser Befehl sorgt dafür, dass ein neues Modul bei Bedarf geladen und initialisiert wird. Ein gutes Beispiel ist hierbei die zentrale Konfigurationsdatei "fhem.cfg" in der sämtliche Devices in Form von <code>define</code>-Statements gespeichert sind.

Damit das funktioniert müssen der Name des Moduls und der Name der [[#X_Initialize|Initialisierungsfunktion]] identisch sein. Das folgende Beispiel soll dies verdeutlichen:

Ein Jeelink USB-Stick könnte beispielsweise mit dem Befehl <code>define JeeLink1 ''JeeLink'' /dev/ttyUSB0@57600</code> definiert werden.

In fhem.pl wird der <code>define</code>-Befehl verarbeitet und geprüft, ob ein Modul mit dem Namen "JeeLink" schon geladen ist. Falls nicht, wird ein Modul mit Namen XY_JeeLink.pm im Modulverzeichnis (z.B. /opt/fhem/FHEM) gesucht und, falls vorhanden, anschließend geladen.
Danach wird die Funktion <code>''JeeLink''_Initialize()</code> aufgerufen um das Modul in FHEM zu registrieren. Eine Moduldatei muss dazu eine Funktion <code>''<Modulname>''_Initialize()</code> enthalten. Durch den Aufruf dieser Funktion wird FHEM mitgeteilt, welche Funktionalitäten dieses Modul unterstützt und durch welche Perl-Funktionen im Modul selbst diese ausimplementiert werden.

In der Initialisierungsfunktion des Moduls werden die Namen aller weiteren Perl-Funktionen des Moduls, die von fhem.pl aus aufgerufen werden, bekannt gemacht. Dazu wird für jedes Modul ein eigener Hash (genauer "Modul-Hash") mit entsprechenden Werten gefüllt, der in fhem.pl für jedes Modul entsprechend abgelegt wird. Dadurch weiß FHEM wie dieses Modul anzusprechen ist.

== Grundlegender Aufbau eines Moduls ==

=== Dateiname ===

Ein FHEM-Modul wird als Perl-Modul mit der Dateiendung *.pm abgespeichert. Der Dateiname folgt dabei folgendem Schema:

:<code>''['''Schlüsselnummer''']''_''['''Modulname''']''.pm</code>

* '''Schlüsselnummer''' - Eine zweistellige Zahl zwischen 00 - 99. Die Schlüsselnummer hat aktuell keine technische Relevanz mehr. In früheren FHEM-Versionen ist sie relevant für [[#Zweistufiges_Modell_f.C3.BCr_Module|zweistufige Module]] (Reihenfolge für [[DevelopmentModuleAPI#Dispatch|Dispatch()]] um logische Module zu prüfen). Die allgemeine Empfehlung ist hierbei eine Schlüsselnummer eines Moduls zu verwenden, welches eine ähnliche Funktionalität bietet. Die Schlüsselnummer 99 hat hierbei eine besondere Bedeutung, da alle Module mit dieser Schlüsselnummer beim Start von FHEM automatisch geladen werden, selbst, wenn sie in der Konfiguration nicht verwendet werden. Daher wird für myUtils 99 als Schlüsselnummer verwendet (99_myUtils.pm). Module mit der Schlüsselnummer 99 werden im SVN nicht akzeptiert (siehe [[SVN Nutzungsregeln]])
* '''Modulname''' - Der Name des Moduls wie er in FHEM bei dem Anlegen einer Gerätedefinition zu verwenden ist. Der Modulname sollte nur aus den folgenden möglichen Zeichen bestehen: Groß-/Kleinbuchstaben, Zahlen sowie Unterstrich (_)

=== Inhaltlicher Aufbau ===

Ein Modul ist inhaltlich in folgende Abschnitte unterteilt:

<syntaxhighlight lang="perl">
#
# 72_MYMODULE.pm
#

package main;

# Laden evtl. abhängiger Perl- bzw. FHEM-Hilfsmodule
use HttpUtils;
use [...]

# FHEM Modulfunktionen

sub MYMODULE_Initialize() {
...
}

sub MYMODULE_Define() {
...
}

...

# Eval-Rückgabewert für erfolgreiches
# Laden des Moduls
1;

# Beginn der Commandref

=pod
=item [helper|device|command]
=item summary Kurzbeschreibung in Englisch was MYMODULE steuert/unterstützt
=item summary_DE Kurzbeschreibung in Deutsch was MYMODULE steuert/unterstützt

=begin html
Englische Commandref in HTML
=end html

=begin html_DE
Deutsche Commandref in HTML
=end html

# Ende der Commandref
=cut
</syntaxhighlight>

Man kann hierbei von folgender Reihenfolge sprechen:

# Perl-Code, welcher das Modul implementiert
# Die Zeile <code>1;</code> nachdem der Perl-Code abgeschlossen ist. Dies dient FHEM der Erkennung, dass das Modul erfolgreich und vollständig geladen wurde. Sollte diese Zeile nicht enthalten sein, wird FHEM beim Laden des Moduls die Fehlermeldung <code>Error:Modul 72_MYMODULE deactivated</code> in das Logfile schreiben.
# Commandref zur Dokumentation des Moduls. Diese Dokumentation soll dem User die möglichen Befehle/Attribute/Readings/Events vermitteln. Weitere Informationen und Hinweise findet man in den [[Guidelines zur Dokumentation]].

== Der Hash einer Geräteinstanz ==
Eine Besonderheit in Perl sind [http://de.wikipedia.org/wiki/Assoziatives_Array#Perl assoziative Arrays], (nicht ganz richtig als "Hash" bezeichnet) in denen die Adressierung nicht über eine Zählvariable erfolgt, sondern über einen beliebigen String. Die internen Abläufe bei der Adressierung führen dazu, dass die Speicherung in und der Abruf aus Hashes relativ langsam ist.

Der zentrale Speicherort für Informationen einer Geräteinstanz bei FHEM ist ein solcher Hash, der seinerseits in fhem.pl von einem globalen Hash referenziert wird.

In fhem.pl werden alle Gerätedefinitionen in dem globalen Hash <code>%defs</code> abgelegt. Der Inhalt von <code>$defs{''<Name>''}</code> in fhem.pl verweist dabei auf den Hash der Geräteinstanz in Form einer Hashreferenz. Diesen Verweis (also nur die Adresse) bekommen die Funktionen eines Moduls übergeben (i.d.R. als <code>$hash</code> bezeichnet), welche direkt von fhem.pl aufgerufen werden. In dem Hash stehen beispielsweise die internen Werte des Geräts, die im Frontend als "Internals" angezeigt werden, sowie die Readings des Geräts.

Beispiele:
*<code>$hash->{NAME}</code> enthält den Namen der Geräteinstanz,
*<code>$hash->{TYPE}</code> enthält die Typbezeichnung des Geräts (Modulname)

==Ausführung von Modulen==
FHEM arbeitet intern nicht parallel, sondern arbeitet alle Aufgaben seriell nacheinander kontinuierlich ab. Daher wäre es ungünstig, wenn Module Daten von einem physikalischen Gerät abfragen wollen und dabei innerhalb der selben Funktion auf die Antwort des Geräts warten. In dieser Zeit, in der FHEM auf die Antwort des Gerätes warten muss, wäre der Rest von FHEM blockiert. Da immer nur eine Aufgabe zur selben Zeit bearbeitet wird, müssen alle weiteren Aufgaben solange warten. Eine Datenkommunikation innerhalb eines Moduls sollte daher immer ohne Blockierung erfolgen. Dadurch kann FHEM die Wartezeit effizient für andere Aufgaben nutzen um bspw. anstehende Daten für andere Module zu verarbeiten. Es gibt in FHEM entsprechende Mechanismen, welche eine "Non-Blocking"-Kommunikation über verschiedene Wege (z.B. seriell, HTTP, TCP, ...) ermöglichen.

Dafür werden in FHEM zwei zentrale Listen gepflegt, in der die Filedeskriptoren der geöffneten Kommunikatonsverbindungen gespeichert sind. Auf Linux- bzw. Unix-basierten Plattformen wird der select-Befehl des Betriebssystems verwendet um Filedeskriptoren auf lesbare Daten zu überprüfen. In FHEM gibt es dazu eine Liste (<code>%selectlist</code>), in der die Filedeskriptoren sämtlicher Geräte (z.B. serielle Verbindung, TCP-Verbindung, etc.) gespeichert sind.

In der zentralen Schleife (Main-Loop) von fhem.pl wird mit <code>select()</code> überwacht, ob über eine der geöffneten Schnittstellen Daten zum Lesen anstehen. Wenn dies der Fall ist, dann wird die Lesefunktion ([[#X_Read|X_Read]]) des zuständigen Moduls aufgerufen, damit es die Daten entgegennimmt und verarbeitet. Anschließend wird die Schleife weiter ausgeführt.

Auf Windows-Systemen funktioniert dies anders. Hier können USB/Seriell-Geräte nicht per <code>select()</code> überwacht werden. In FHEM unter Windows werden daher diese Schnittstellen kontinuierlich abgefragt ob Daten bereitstehen. Dafür müssen Module zusätzlich zur Lesefunktion eine Abfragefunktion ([[#X_Ready|X_Ready]]) implementieren, welche prüft, ob Daten zum Lesen anstehen. Auch auf Linux/Unix-Plattformen hat diese Funktion eine Aufgabe. Falls nämlich eine Schnittstelle ausfällt, beziehungsweise ein CUL oder USB-zu-Seriell Adapter ausgesteckt wird, dann wird über diese Funktion regelmäßig geprüft ob die Schnittstelle wieder verfügbar wird.

Innerhalb der eigentlichen Lesefunktion (X_Read) werden dann die Daten vom zugehörigen Gerät gelesen, das nötige Protokoll implementiert um die Daten zu interpretieren und Werte in Readings geschrieben.

Auch wenn von einem Anwender über einen Get-Befehl Daten aktiv von einem Gerät angefordert werden, sollte nicht blockierend gewartet werden. Eine asynchrone Ausgabe, sobald das Ergebnis vorliegt, ist über [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] möglich. Siehe {{Link2Forum|Topic=43771|Message=357870|LinkText=Beschreibung}} und {{Link2Forum|Topic=43771|Message=360935|LinkText=Beispiel}}. Weitere Anwendungsbeispiele finden sich im {{Link2Forum|Topic=43052|Message=353477|LinkText=PLEX Modul}} und im überarbeiteten und nicht-blockierenden {{Link2Forum|Topic=42771|Message=348498|LinkText=SYSSTAT Modul}}.

== Wichtige globale Variablen aus fhem.pl ==

FHEM arbeitet mit einer Vielzahl an internen Variablen. Die nun folgenden aufgelisteten Variablen sind die wichtigsten, welche man im Rahmen der Modulprogrammierung kennen sollte:

{| class="wikitable"
|-
! Variable !! Beschreibung
|-
| <code>$init_done</code> || Dient der Erkennung für fhem.pl sowie den Modulen, ob FHEM den Initialisierungsvorgang abgeschlossen hat. Beim Starten von FHEM ist <code>$init_done</code> gleich <code>0</code>. Erst, wenn das Einlesen der Konfiguration, sowie des State-Files (Readings) abgeschlossen ist, wird <code>$init_done</code> auf <code>1</code> gesetzt.
Das gleiche Verfahren wird auch bei dem Befehl <code>rereadcfg</code> angewandt. Während <code>rereadcfg</code> ausgeführt wird (Konfiguration löschen, neu einlesen), ist <code>$init_done</code> gleich <code>0</code>.

Dies ist insbesondere in der [[#X_Define|Define]]-Funktion eines Moduls relevant. Durch eine Prüfung auf <code>$init_done</code> kann man erkennen, ob eine Definition von Hand (<code>$init_done</code> = 1) oder im Rahmen der Initialisierung (FHEM Start / Rereadcfg => <code>$init_done</code> = 0) erfolgte. Während der Initialisierung stehen bspw. die gesetzten Attribute der Definition noch nicht zur Verfügung und können daher nicht ausgewertet werden (siehe .
|-
| <code>%attr</code> || In <code>%attr</code> werden sämtliche gesetzten Attribute aller Geräte gespeichert. Diese Datenstruktur wird generell durch den <code>attr</code>-Befehl verwaltet. Hierbei wird einem Gerätenamen eine Mehrzahl an Attributnamen mit einem Wert zugeordnet. Attribut-Inhalte können über die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] ausgelesen werden.
|-
| <code>%cmds</code> || In <code>%cmds</code> wird jedem in FHEM existierendem Befehl die entsprechende Funktion zugewiesen, welche diesen Befehl umsetzt. Module können durch das Eintragen eines Befehlsnamen samt Funktion in <code>%cmds</code> über die [[#X_Initialize|Initialize]]-Funktion eines Moduls einen (oder mehrere) eigene Befehle in FHEM registrieren.

Die Struktur ist dabei wiefolgt:

$cmds{''<Befehlsname>''} = { Fn => "''<Funktionsname>''",
Hlp => "''<Aufrufsyntax>''"};

|-
| <code>%data</code>|| Der eigentliche Zweck von <code>%data</code> ist dem Nutzer eine Möglichkeit zum Speichern von temporären Daten im globalen Kontext zu ermöglichen. Einige Module verwenden <code>%data</code> jedoch auch um modul- & geräteübergreifend Daten auszutauschen.
|-
| <code>%defs</code>|| In <code>%defs</code> werden sämtliche Gerätedefinitionen, bzw. die Hash-Referenzen auf diese, gespeichert. Hier ist jedem Gerätenamen eine Hash-Referenz zugeordnet.
|-
| <code>%modules</code>|| In <code>%modules</code> sind alle geladenen Module gelistet mit ihren entsprechenden Initialisierungsdaten (Funktionsnamen, Attribut-Listen, spezielle Einstellungen, ...). Hier wird für jeden Modulname der Modul-Hash aus der [[#X_Initialize|Initialize]]-Funktion gespeichert.
Desweiteren legen viele Module, welche nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] hier eine Rückwärtszuordnung von Geräteadressen zu Geräte-Hash an.
|-
| <code>%readyfnlist</code>|| In <code>%readyfnlist</code> sind alle zu prüfenden Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte regelmäßig über eine Aufruf der entsprechenden [[#X_Ready|Ready]]-Funktion.

Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%readyfnlist</code>.
|-
| <code>%selectlist</code>|| In <code>%selectlist</code> sind alle geöffneten Verbindungen mit ihrer entsprechendem Geräte-Hash gelistet. FHEM prüft alle hier gelisteten Geräte, ob der geöffnete Filedeskriptor unter <code>$hash->{FD}</code> Daten zum Lesen bereitgestellt hat. Ist dass der Fall, wird die entsprechende [[#X_Read|Read]]-Funktion aufgerufen, um anstehende Daten durch das Modul zu verarbeiten.
Bei einer Nutzung von dem Hilfsmodul [[DevIo|DevIo.pm]] zum Aufbau einer Kommunikationsverbindung, kümmert sich DevIo selbständig um den entsprechenden Eintrag in <code>%selectlist</code>.
|}

Es gibt durchaus viele weitere globale Variablen, die jedoch für sehr spezielle Anwendungsfälle und z.T. nur einzelne Module gedacht sind und daher hier nicht aufgeführt werden.

== Internals ==
Daten, die ein Modul im Geräte-Hash speichert nennt man Internals. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielswiese <code>$hash->{NAME}</code> für den Gerätenamen, welcher beim Define-Befehl übergeben wurde und als Internal gespeichert wird. Diese Daten spielen für FHEM eine sehr wichtige Rolle, da sämtliche gerätespezifischen Daten als Internal im Gerätehash gespeichert werden.

Falls Werte wie z.B. ein Intervall nicht über den Define-Befehl gesetzt werden sollen und im Betrieb einfach änderbar sein sollten, ist eine alternative Möglichkeit die Speicherung in so genannten Attributen. Dann würde man den Define-Befehl so implementieren, dass er kein Intervall übergeben bekommt und statt dessen das Interval als Attribut über den Befehl <code>attr</code> gesetzt wird.

Generell werden alle Werte, welche direkt in der ersten Ebene von <code>$hash</code> (Gerätehash) gespeichert werden auf der Detail-Seite einer Definition in der FHEMWEB Oberfläche angezeigt. Es gibt jedoch Ausnahmen:

* <code>$hash->{helper}{URL}</code> - Alle Elemente, welche als Unterelement wieder einen Hash besitzen werden nicht in FHEMWEB dargestellt. Typischerweise speichern Module Daten unter <code>$hash->{helper}</code> interne Daten zwischen, die für den User nicht relevant sind, sondern nur der internen Verarbeitung dienen.
* <code>$hash->{'''.'''ELEMENT}</code> - Alle Knoten, welche mit einem Punkt beginnen werden in der FHEMWEB Oberfläche nicht angezeigt. Man kann diese Daten jedoch beim Aufruf des [[List|list-Kommandos]] einsehen.

Es gibt bereits vorbelegte Internals welche in FHEM dazu dienen definitionsbezogene Informationen wie bspw. Namen und Readings zu speichern. Dies sind im besonderen:

{| class="wikitable"
|-
! style="min-width: 13em;" | Internal !! Beschreibung
|-
| <code>$hash->{NAME}</code> || Der Definitionsname, mit dem das Gerät angelegt wurde.
|-
| <code>$hash->{READINGS}</code> || Enthält alle aktuell vorhandenen Readings. Daten unterhalb dieses Knotens sollte man nicht direkt manipulieren. Um Readings zu Erzeugen gibt es entsprechende [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]].
|-
| <code>$hash->{NR}</code> || Die Positions-Nr. der Definition innerhalb der Konfiguration. Diese dient dazu die Konfiguration in der gleichen Reihenfolge zu speichern, wie die einzelnen Geräte angelegt wurden.
|-
| <code>$hash->{TYPE}</code> || Der Modulname, mit welchem die Definition angelegt wurde.
|-
| <code>$hash->{DEF}</code> || Sämtliche Argumente, welche beim <code>define</code>-Befehl nach dem Modulnamen übergeben wurden.
|-
| <code>$hash->{CFGFN}</code> || Der Dateiname der Konfigurationsdatei in der diese Definition enthalten ist (sofern nicht in fhem.cfg). Dieser Wert ist nur gefüllt, wenn man mit mehreren Konfigurationsdateien arbeitet, welche dann in fhem.cfg via include-Befehl eingebunden werden.
|-
| <code>$hash->{NTFY_ORDER}</code> || Sofern das Modul Events via [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] verarbeitet enthält jede Definition eine Notify-Order als Zeichenkette bestehend aus dem Notify Order Prefix und dem Definitionsnamen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Reihenfolge für den Aufruf der Notify-Funktion beeinflussen".
|-
| <code>$hash->{NOTIFYDEV}</code> || Sofern das Modul Events via NotifyFn verarbeitet kann man damit die Definitionen, von denen man Events erhalten will begrenzen. Details zur Funktionsweise gibt es in der Beschreibung zur [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] im Abschnitt "Begrenzung der Aufrufe auf bestimmte Geräte".
|-
| <code>$hash->{IODev}</code> || Hier wird das zugeordnete IO-Gerät durch [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] gespeichert, welches für den Datentransport und -empfang dieses logischen Gerätes zuständig ist. Dieser Wert existiert nur bei Modulen die nach dem [[DevelopmentModuleIntro#Zweistufiges_Modell_f.C3.BCr_Module|zweistufigen Modulkonzept]] arbeiten.
|-
| <code>$hash->{CHANGED}</code> || Hier werden alle Events kurzzeitig gesammelt, welche für die Eventverarbeitung anstehen. Insbesondere die [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] speichern hier alle Events zwischen um sie nach Abschluss via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] zu verarbeiten.
|-
| <code>$hash->{FD}</code> || Wenn die Definition eine Netzwerkverbindung oder serielle Schnittstelle geöffnet hat (z.B. via [[DevIo]]), so wird der entsprechende File-Deskriptor in diesem Internal gespeichert. Damit kann FHEM alle geöffneten Filedeskriptoren der entsprechenden Definition zuordnen um bei ankommenden Daten die Definition via [[DevelopmentModuleIntro#X_Read|Read-Funktion]] damit zu versorgen.
|-
| <code>$hash->{EXCEPT_FD}</code> || Ähnlich wie <code>$hash->{FD}</code>. Sofern die Definition in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> eingetragen ist und ein Fildeskriptor in diesem Internal gesetzt ist, wird bei einer auftretenden Exception bzw. Interrupt die [[DevelopmentModuleIntro#X_Except|Except]]-Funktion des entsprechenden Moduls aufgerufen um darauf zu reagieren.
|}

Generell sollte man die meisten der hier genannten systemweiten Internals nicht modifizieren, da ansonsten die korrekte Funktionsweise von FHEM nicht mehr garantiert werden kann.

== Readings ==
Daten, welche von einem Gerät gelesen werden und in FHEM in einer für Menschen verständlichen Form zur Verfügung gestellt werden können, werden Readings genannt. Sie geben den Status des Gerätes wieder und erzeugen Events innerhalb von FHEM auf die andere Geräte reagieren können. Sie werden als Unterstruktur des Hashes der jeweiligen Geräteinstanz gespeichert, beispielsweise
*<code>$hash->{READINGS}{temperature}{VAL}</code> für die Temperatur eines Fühlers
*<code>$hash->{READINGS}{temperature}{TIME}</code> für den Zeitstempel der Messung

Für den lesenden Zugriff auf Readings steht die Funktion <code>[[DevelopmentModuleAPI#ReadingsVal|ReadingsVal()]]</code> zur Verfügung. Ein direkter Zugriff auf die Datenstruktur sollte nicht vorgenommen werden.

Readings werden im Statefile von FHEM automatisch auf der Festplatte zwischengespeichert, damit sie nach einem Neustart sofort wieder zur Verfügung stehen. Dadurch ist der letzte Status eines Gerätes vor einem Neustart nachvollziehbar.

Readings, die mit einem Punkt im Namen beginnen, haben eine funktionale Besonderheit. Sie werden im FHEMWEB nicht angezeigt und können somit als "Permanentspeicher" für kleinere Daten innerhalb des Moduls genutzt werden. Um größere Datenmengen permanent zu speichern sollte man jedoch die Funktion <code>[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]</code> verwenden.

Zum Setzen von Readings sollen
*bei Gruppen von Readings der Funktionsblock <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code> (mehrfach wiederholt), <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code>
*bei einzelnen Updates die Funktion <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code>
aufgerufen werden. Dabei kann man auch angeben, ob dabei ein Event ausgelöst werden soll oder nicht. Events erzeugen, je nach Hardwareperformance, spürbare Last auf dem System (siehe [[DevelopmentModuleIntro#X_Notify|NotifyFn]]), das Ändern von Readings ohne dass dabei Events erzeugt werden jedoch nicht.

Eine Sequenz zum Setzen von Readings könnte folgendermaßen aussehen:

<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, $readingName1, $wert1 );
readingsBulkUpdate($hash, $readingName2, $wert2 );
readingsEndUpdate($hash, 1);
</syntaxhighlight>

Um Readings zu löschen, wird für die Modulprogrammierung die Funktion <code>[[DevelopmentModuleAPI#readingsDelete|readingsDelete()]]</code> empfohlen. Beispiel:

<syntaxhighlight lang="perl">
readingsDelete($hash, $readingsname)
</syntaxhighlight>
{{Hinweis|'''Hintergrundinfo dazu aus dem Forum:''' {{Link2Forum|Topic=83069|Message=753066}}

<code>CommandDeleteReading()</code> bzw. <code>deletereading</code> ist eher fuer den Endbenutzer und seine userReadings gedacht, und macht bei den Modulen die unnoetige Schleife ueber [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wenn der Modulautor beim Aufruf auch <code>$cl</code> weitergibt, und der Anwender meint, dieses Geraet auf blacklist setzen zu muessen, dann kann das Modul sein eigenes Reading nicht entfernen, und das ist kontraproduktiv.
}}

== Events ==

FHEM verfügt über einen Event-Mechanismus um Änderungen verschiedenster Art an einzelne oder alle Definitionen mitzuteilen. Jedes Modul (und damit alle Definitionen dieses Moduls) können auf Events von FHEM selber (Definition <code>global</code>) oder von anderen Definitionen reagieren und dadurch selber aktiv werden. Ein Event wird innerhalb von FHEM als Zeichenkette behandelt.

Events sind grundsätzlich immer definitionsbezogen. Das bedeutet, dass ein Event immer in Verbindung mit einem Definitionsnamen erzeugt wird. Jede Definition, welche ein Event verarbeitet, erhält den Definitions-Hash (<code>$hash</code>) der auslösenden Definition.

Events werden typischerweise bei der Erstellung von Readings implizit für jedes einzelne Reading erzeugt. Es gibt jedoch auch Events die nichts mit Readings zu tun haben um anderweitige Änderungen bekannt zu geben.

Eigene Events können in FHEM mit der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] erzeugt werden. Um auf Events in einem Modul reagieren zu können, muss eine [[#X_Notify|Notify]]-Funktion implementiert sein. Sobald ein oder mehrere Events für eine Definition getriggert werden, prüft FHEM, welche Definitionen über Events der auslösenden Definition informiert werden möchten. Diese werden dann nacheinander in einer bestimmten Reihenfolge durch Aufruf der [[#X_Notify|Notify]]-Funktion über anstehende Events in Kenntnis gesetzt. Es obliegt dann dem jeweiligen Modul, wie es auf die Events reagiert.

=== globale Events ===

Als "globale Events" werden alle Events bezeichnet, die durch die Definition <code>global</code> erzeugt werden. Es handelt sich hierbei um Events die Strukturänderungen in der Konfiguration, als auch systemweite Ereignisse zu FHEM selbst signalisieren.

Hier eine kurze Zusammenfassung, welche Events durch <code>global</code> getriggert werden können:

Allgemeine Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>INITIALIZED</code>''' || Der Start von FHEM ist abgeschlossen. Sämtliche Definitionen und Attribute wurden aus der Konfiguration (fhem.cfg oder configDB) eingelesen, sowie sämtliche Readings sind aus dem State-File eingelesen und stehen nun voll umfänglich zur Verfügung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>REREADCFG</code>''' || Die Konfiguration wurde erneut eingelesen. Dies bedeutet, es wurden alle Definitionen/Attribute/Readings aus FHEM entfernt und durch Einlesen der Konfiguration neu angelegt. (FHEM-Befehl: "rereadcfg")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SAVE</code>''' || Die laufende Konfiguration soll gespeichert werden (in fhem.cfg oder configDB). Dieses Event wird '''VOR''' dem Speichern der Konfiguration getriggert. Sobald der Trigger verarbeitet wurde, beginnt das Speichern der Konfiguration. (FHEM-Befehl: "save")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>SHUTDOWN</code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code> DELAYEDSHUTDOWN </code>''' || FHEM wird sich beenden. (FHEM-Befehl: "shutdown")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UPDATE</code>''' || Es wurde ein Update erfolgreich installiert. (FHEM-Befehl: "update")
|}

Definitionsbezogene Events:

{| class="wikitable"
|-
! Event-Text !! Beschreibung.
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DEFINED ''<Name>''</code>''' || Es wurde eine neue Definition mit Namen <code>''<Name>''</code> angelegt. (FHEM-Befehl: "define")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>DELETED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde gelöscht. (FHEM-Befehl: "delete")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>RENAMED ''<Alt>'' ''<Neu>''</code>''' || Die Definition mit dem Namen <code>''<Alt>''</code> wurde in den Namen <code>''<Neu>''</code> umbenannt. (FHEM-Befehl: "rename")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>MODIFIED ''<Name>''</code>''' || Die Definition mit dem Namen <code>''<Name>''</code> wurde modifiziert. (FHEM-Befehl: "modify")
|-
| style="vertical-align:top; white-space: nowrap;" | '''<code>UNDEFINED ''<Name> <Modul> <Define-Parameter>''</code>''' || Es wurde eine Nachricht von einem physikalischen Modul (siehe [[#Zweistufiges Modell für Module|zweistufiges Modulkonzept]]) erhalten, für die keine passende logische Definition in FHEM existiert. Details dazu, siehe dazu Abschnitt [[#Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)|Automatisches Anlegen von logischen Gerätedefinitionen (autocreate)]].
|}

=== Begrenzung von Events ===

Ein Modul, welches Events verarbeitet, kann die Eventverarbeitung auf bestimmte Definitionen begrenzen. Dadurch werden nur Events an das Modul gemeldet (via [[#X_Notify|X_Notify()]]), welche von einer oder mehreren bestimmten Definitionen getriggert wurden. Dadurch werden unnötige Events nicht an das Modul gemeldet und schont somit Ressourcen.

Standardmäßig werden sämtliche Events ohne Begrenzung an ein Modul gemeldet, welches eine [[#X_Notify|Notify]]-Funktion implementiert hat und somit Events verarbeiten kann. Details zur Begrenzung von Events findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

=== Reihenfolge der Eventverarbeitung ===

Ein getriggertes Event wird nacheinander gegen jede Definition geprüft, deren Modul eine [[#X_Notify|Notify]]-Funktion implementiert hat. Dies bedeutet, jede Definition wird nacheinander durch Aufruf der [[#X_Notify|Notify]]-Funktion mit dem Definitionshash der auslösenden Definition aufgerufen.

Unter bestimmten Umständen kann es erforderlich sein, in diese Reihenfolge einzugreifen. Beispielsweise wenn das eigene Modul und deren Definitionen das Event als letztes oder erstes verarbeiten müssen. Ein Beispiel bietet hierbei das Modul [[dewpoint]], welches Events vor allen anderen Modulen verarbeiten muss.

Details, wie man die Reihenfolge der Eventverarbeitung steuern kann, findet man in der Beschreibung zur Modulfunktion [[#X_Notify|X_Notify()]].

== Attribute ==
Damit der Nutzer das Verhalten einer einzelnen Gerätedefinition zur Laufzeit individuell anpassen kann, gibt es in FHEM für jede Definition sogenannte Attribute, welche mit dem Befehl <code>attr</code> gesetzt werden können.
Diese stehen dann dem Modul unmittelbar zur Verfügung um das Verhalten während der Ausführung zu beeinflussen. Attribute werden zusammen mit dem <code>define</code>-Befehl der jeweiligen Definition beim Speichern der aktuellen Konfiguration von FHEM in die Konfigurationsdatei geschrieben. Beim Neustart werden die entsprechenden Befehle ausgeführt um alle Definition inkl. Attribute wieder anzulegen. Zur Laufzeit werden Attribute in dem globalen Hash <code>%attr</code> mit dem Definitionsnamen als Index (<code>$attr{$name} = $value</code>) gespeichert. Ein Attribut mit dem Namen <code>header</code> würde beispielsweise mit <code>$attr{$name}{header}</code> adressiert. Generell sollte <code>%attr</code> nicht durch direkten Zugriff manipuliert/benutzt werden.

Zum Auslesen von Attributen sollte die Funktion [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verwendet werden.

Welche Attribute ein Modul unterstützt muss in der Funktion <code>[[#X_Initialize|X_Initialize]]</code> durch Setzen von <code>$hash->{AttrList}</code> bekannt gemacht werden (siehe unten).

Wenn beim Setzen von Attributen in einer Gerätedefinition entsprechende Werte geprüft werden sollen oder zusätzliche Funktionalitäten implementiert werden müssen, dann muss dies in der Funktion <code>[[#X_Attr|X_Attr]]</code> (siehe unten) implementiert werden. Hier kann man bspw. einen Syntaxcheck für Attribut-Werte implementieren um ungültige Werte zurückzuweisen.

== Modulfunktionen ==

Damit fhem.pl ein Modul nutzen kann, muss dieses entsprechende Funktionen mit einer vorgegebenen Aufrufsyntax implementieren. Durch die Bekanntgabe dieser modulspezifischen Funktionen können Daten zwischen fhem.pl und einem Modul entsprechend ausgetauscht werden. Es gibt verschiedene Arten von Funktionen die ein Modul anbieten muss bzw. kann, je nach Funktionsumfang.

=== Die wichtigsten Funktionen in einem Modul ===

Folgende Funktion muss ein Modul mit dem beispielhaften Namen "X" mindestens bereitstellen:

{| class="wikitable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" | Kurzbeschreibung
|-
| [[#X_Initialize|X_Initialize]] || Initialisiert das Modul und gibt den Namen zusätzlicher Modulfunktionen bekannt, sowie modulspezifische Einstellungen. Wird direkt nach dem erfolgreichen Laden des Moduls durch fhem.pl aufgerufen.
|}

Die folgenden Funktionen sind die wichtigsten Funktionen, welche je nach Anwendungsfall zu implementieren sind. Es handelt sich hierbei um die wichtigsten Vertreter, welche in den meisten Modulen Verwendung finden. Nicht alle Funktionen machen jedoch in jedem Modul Sinn. Generell sollte auch hier bei jeder Funktion der Modulname vorangestellt werden um ein einheitliches Namensschema zu gewährleisten. Hier die wichtigsten Modulfunktionen:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Define|X_Define]] || Wird im Rahmen des <code>define</code>-Befehls aufgerufen.
|-
| [[#X_Undef|X_Undef]] || Wird im Rahmen des <code>delete</code>-Befehls, sowie <code>rereadcfg</code>-Befehl aufgerufen. Dient zum Abbau von offenen Verbindungen, Timern, etc.
|-
| [[#X_Delete|X_Delete]] || Wird im Rahmen des beim <code>delete</code>-Befehls aufgerufen wenn das Gerät endgültig gelöscht wird um weiterführende Aktionen vor dem Löschen durchzuführen.
|-
| [[#X_Get|X_Get]] || Wird im Rahmen des <code>get</code>-Befehls aufgerufen um Daten vom Gerät abzufragen
|-
| [[#X_Set|X_Set]] || Wird im Rahmen des <code>set</code>-Befehls aufgerufen um Daten an das Gerät zu senden.
|-
| [[#X_Attr|X_Attr]] || Wird im Rahmen des <code>attr</code>-Befehls aufgerufen um Attributwerte zu prüfen)
|-
| [[#X_Read|X_Read]] || Wird durch FHEM aufgerufen, wenn ein gelisteter Filedeskriptor in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> Daten zum Lesen bereitstellt.
|-
| [[#X_Ready|X_Ready]] || Wird unter Windows durch FHEM aufgerufen um zyklisch einen seriellen Filedeskriptor auf lesbare Daten zu prüfen. Unter Linux dient diese Funktion dem Wiederaufbau verlorener Verbindungen.
|-
| [[#X_Notify|X_Notify]] || Verarbeitet Events von anderen Geräten innerhalb von FHEM
|-
| [[#X_Rename|X_Rename]] || Wird aufgerufen, wenn ein Gerät umbenannt wird.
|-
| [[#X_Shutdown|X_Shutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|-
| [[#X_DelayedShutdown | X_DelayedShutdown]] || Wird beim Herunterfahren von FHEM ausgeführt.
|}

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Initialize ====

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
}
</syntaxhighlight>

Das <code>X</code> im Namen muss dabei auf den Namen des Moduls bzw. des definierten Gerätetyps geändert werden. Im Modul mit der Datei <code>36_JeeLink.pm</code> beispielsweise ist der Name der Funktion <code>JeeLink_Initialize</code>. Die Funktion wird von fhem.pl nach dem Laden des Moduls aufgerufen und bekommt eine leere Hashreferenz für den Initialisierungsvorgang übergeben.

Dieser Hash muss nun von X_Initialize mit allen modulrelevanten Funktionsnamen gefüllt werden. Anschließend wird dieser Hash durch fhem.pl im globalen Hash <code>%modules</code> gespeichert. <code>$modules{ModulName}</code> wäre dabei der Hash für das Modul mit dem Namen <code>ModulName</code>. Es handelt sich also nicht um den oben beschriebenen Hash der Geräteinstanzen sondern einen Hash, der für jedes Modul existiert und modulspezifische Daten wie bspw. die implementierten Modulfunktionen enthält. Die Initialize-Funktion setzt diese Funktionsnamen, in den Hash des Moduls wie folgt:

<syntaxhighlight lang="perl">
$hash->{DefFn} = "X_Define";
$hash->{UndefFn} = "X_Undef";
$hash->{DeleteFn} = "X_Delete";
$hash->{SetFn} = "X_Set";
$hash->{GetFn} = "X_Get";
$hash->{AttrFn} = "X_Attr";
$hash->{ReadFn} = "X_Read";
$hash->{ReadyFn} = "X_Ready";
$hash->{NotifyFn} = "X_Notify";
$hash->{RenameFn} = "X_Rename";
$hash->{ShutdownFn} = "X_Shutdown";
$hash->{DelayedShutdownFn} = "X_ DelayedShutdown";
</syntaxhighlight>

Um eine entsprechende Funktion in FHEM bekannt zu machen muss dazu der Funktionsname, wie er im Modul als <code>sub <''Funktionsname''>() { ... }</code> definiert ist, als Zeichenkette in <code>$hash</code> gesetzt werden. Dabei sollten die entsprechenden Funktionsnamen immer den Modulnamen (in diesem Beispiel <code>X</code>) als Präfix verwenden.
Auf diese Weise können sämtliche modulspezifisch implementierten Funktionen wie <code>X_Read</code>, <code>X_Parse</code> etc. durch Zuweisung an <code>$hash->{ReadFn}</code> bzw. <code>$hash->{ParseFn}</code> usw. bekannt gemacht werden.

Darüber hinaus sollten die vom Modul unterstützten Attribute definiert werden:

<syntaxhighlight lang="perl">
$hash->{AttrList} =
"do_not_notify:1,0 " .
"header " .
$readingFnAttributes;
</syntaxhighlight>

Die Auflistung aller unterstützten modulspezifischen Attribute erfolgt in Form einer durch Leerzeichen getrennten Liste in <code>$hash->{AttrList}</code>. Es gibt in FHEM globale Attribute, die in allen Gerätedefinitionen verfügbar sind und nur modulspezifische Attribute die jedes Modul via <code>$hash->{AttrList}</code> über die eigene Initialize-Funktion setzt. In fhem.pl werden dann die entsprechenden Attributwerte beim Aufruf eines <code>attr</code>-Befehls in die globale Datenstruktur <code>$attr{$name}</code>, z.B. <code>$attr{$name}{header}</code> für das Attribut <code>header</code> gespeichert. Falls im Modul weitere Aktionen oder Prüfungen beim Setzen eines Attributs nötig sind, dann kann wie im Beispiel oben die [[#X_Attr|Attr]]-Funktion implementiert und in der Initialize-Funktion bekannt gemacht werden.

Die Variable <code>$readingFnAttributes</code>, die im obigen Beispiel an die Liste der unterstützten Attribute angefügt wird, definiert Attributnamen, die dann zusätzlich gemacht werden, wenn das Modul zum Setzen von Readings die Funktionen <code>[[DevelopmentModuleAPI#readingsBeginUpdate|readingsBeginUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsBulkUpdate|readingsBulkUpdate()]]</code>, <code>[[DevelopmentModuleAPI#readingsEndUpdate|readingsEndUpdate()]]</code> oder <code>[[DevelopmentModuleAPI#readingsSingleUpdate|readingsSingleUpdate()]]</code> verwendet. In diesen Funktionen werden Attribute wie <code>event-min-interval</code> oder auch <code>event-on-change-reading</code> ausgewertet. Für Details hierzu siehe commandref zu {{Link2CmdRef|Anker=readingFnAttributes|Label=readingFnAttributes}}.

Nutzung von parseParams()

Die Funktion <code> [[DevelopmentModuleAPI#parseParams|parseParams()]]</code> unterstützt Modul-Autoren beim Parsen von Übergabeparametern, welche bei <code>define</code>, <code>get</code> und <code>set</code> Kommandos an die entsprechenden Modulfunktionen übergeben werden. Dadurch lassen sich auf einfache Weise insbesondere komplexe Parameter (wie bspw. Perl-Ausdrücke) sehr einfach parsen.

Diese Zusatzfunktion kann man in der Initialize-Funktion einfach über folgenden Parameter für [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion modulweit aktivieren:
<syntaxhighlight lang="perl">$hash->{parseParams} = 1;</syntaxhighlight>
Sobald es gesetzt ist wird automatisch durch fhem.pl <code>[[DevelopmentModuleAPI#parseParams|parseParams()]]</code> aufgerufen und die an die [[#X_Define|Define]]-, [[#X_Get|Get]]- und [[#X_Set|Set]]-Funktion übergebenen Parameter ändern sich wie weiter unten in den jeweiligen Funktionen beschrieben.

==== X_Define ====
<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Define-Funktion eines Moduls wird von FHEM aufgerufen wenn der Define-Befehl für ein Geräte ausgeführt wird und das Modul bereits geladen und mit der Initialize-Funktion initialisiert ist. Sie ist typischerweise dazu da, die übergebenen Parameter zu prüfen und an geeigneter Stelle zu speichern sowie einen Kommunikationsweg zum Gerät zu öffnen (z.B. TCP-Verbindung, USB-Schnittstelle o.ä.) oder einen [[#Pollen_von_Geräten|Status-Timer]] zu starten.
Sie beginnt typischerweise mit:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
my @a = split( "[ \t][ \t]*", $def );
...
</syntaxhighlight>

Als Übergabeparameter bekommt die Define-Funktion den Hash der Geräteinstanz sowie den die im <code>define</code>-Befehl übergebenen Parameter. Welche bzw. wie viele Parameter
akzeptiert werden und welcher Syntax diese entsprechen müssen ist Sache dieser Funktion. Im obigen Beispiel wird die Argumentzeile <code>$def</code> in ein Array aufgeteilt (durch Leerzeichen/Tabulator getrennt) und so können die vom Modul bzw. der Define-Funktion erwarteten Werte über das Array der Reihe nach verarbeitet werden:

<syntaxhighlight lang="perl">
my $name = $a[0];
my $module = $a[1];
my $url = $a[2];
my $inter = 300;

if(int(@a) == 4) {
$inter = $a[3];
if ($inter < 5) {
return "interval too small, please use something > 5s, default is 300 seconds";
}
}
</syntaxhighlight>

Damit die übergebenen Werte auch anderen Funktionen zur Verfügung stehen und an die jeweilige Geräteinstanz gebunden sind, werden die Werte typischerweise als Internals im Hash der Geräteinstanz gespeichert:

<syntaxhighlight lang="perl">
$hash->{url} = $url;
$hash->{Interval} = $inter;
</syntaxhighlight>

Sobald alle Parameter korrekt verarbeitet wurden, wird in der Regel die erste Verbindung zum Gerät aufgebaut. Je nach Art des Geräts kann das eine permanente Datenverbindung sein (z.B. serielle Schnittstelle oder TCP-Verbindung) oder das Starten eines regelmäßigen Timers, der zyklisch den Status z.B. via [[HttpUtils|HTTP]] ausliest.

Sollten im Rahmen der Define-Funktion Syntax-Probleme der Übergabeparameter festgestellt werden oder es kann bspw. keine Verbindung aufgebaut werden, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn alle Übergabeparameter akzeptiert werden, darf <code>undef</code> zurückgegeben werden. Sobald eine Define-Funktion eine Fehlermeldung zurückmeldet, wird der define-Befehl durch FHEM zurückgewiesen und der User erhält die Fehlermeldung, welche die Define-Funktion produziert hat, als Ausgabe zurück.

Verfügbarkeit von Attributen

Während die Define-Funktion ausgeführt wird, sollte man nicht davon ausgehen, dass alle vom Nutzer konfigurierten Attribute via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] verfügbar sind. Attribute stehen in der Define-Funktion nur dann zur Verfügung, wenn FHEM sich nicht in der Initialisierungsphase befindet (globale Variable <code>$init_done</code> ist wahr; der Nutzer hat die Gerätedefinition modifiziert). Daher sollte man weiterführende Funktion, welche auf gesetzte Attribute angewiesen sind, nur dann in der Define-Funktion starten, wenn <code>$init_done</code> zutrifft.

Andernfalls sollte man den Aufruf in der Notify-Funktion durchführen sobald <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> getriggert wurde:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;

...

$hash->{NOTIFYDEV} = "global";

X_FunctionWhoNeedsAttr($hash) if($init_done);
}

sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events
my $events = deviceEvents($dev_hash, 1);

if($devName eq "global" && grep(m/^INITIALIZED|REREADCFG$/, @{$events}))
{
X_FunctionWhoNeedsAttr($hash);
}
}
</syntaxhighlight>

Dadurch wird die Modulfunktion X_FunctionWhoNeedsAttr() nach dem Start erst aufgerufen, wenn alle Attribute aus der Konfiguration geladen wurden.

Nutzung von parseParams()

Zum Aufteilen und Parsen von <code>$def</code> lässt sich die Funktion [[DevelopmentModuleAPI#parseParams|parseParams()]] verwenden um die einzelnen Argumente einfach zu parsen. Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird parseParams() automatisch aufgerufen und X_Define() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Define($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Undef ====
<syntaxhighlight lang="perl">
sub X_Undef ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>
Die Undef-Funktion wird aufgerufen wenn ein Gerät mit <code>delete</code> gelöscht wird oder bei der Abarbeitung des Befehls <code>rereadcfg</code>, der ebenfalls alle Geräte löscht und danach das Konfigurationsfile neu einliest. Entsprechend müssen in der Funktion typische Aufräumarbeiten durchgeführt werden wie das saubere Schließen von Verbindungen oder das Entfernen von internen Timern, sofern diese im Modul zum Pollen verwendet wurden (siehe Abschnitt [[#Pollen_von_Geräten|Pollen von Geräten]]).

Zugewiesene Variablen im Hash der Geräteinstanz, Internals oder Readings müssen hier nicht gelöscht werden. In fhem.pl werden die entsprechenden Strukturen beim Löschen der Geräteinstanz ohnehin vollständig gelöscht.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Undef($$)
{
my ( $hash, $name) = @_;
DevIo_CloseDev($hash);
RemoveInternalTimer($hash);
return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Undef-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur wenn die Undef-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht bzw. neu angelegt. Sollte die Undef-Funktion jedoch eine Fehlermeldung zurückgeben, wird der entsprechende Vorgang (<code>delete</code> bzw. <code>rereadcfg</code>) für dieses Gerät abgebrochen. Es bleibt dann unverändert in FHEM bestehen.

==== X_Delete ====
<syntaxhighlight lang="perl">
sub X_Delete ($$)
{
my ( $hash, $name ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Delete-Funktion ist das Gegenstück zur Funktion [[#X_Define|X_Define]] und wird aufgerufen wenn ein Gerät mit dem Befehl <code>delete</code> gelöscht wird.

Wenn ein Gerät in FHEM gelöscht wird, wird zuerst die Funktion [[#X_Undef|X_Undef]] aufgerufen um offene Verbindungen zu schließen, anschließend wird die Funktion X_Delete aufgerufen. Diese dient eher zum Aufräumen von dauerhaften Daten, welche durch das Modul evtl. für dieses Gerät spezifisch erstellt worden sind. Es geht hier also eher darum, alle Spuren sowohl im laufenden FHEM-Prozess, als auch dauerhafte Daten bspw. im physikalischen Gerät zu löschen die mit dieser Gerätedefinition zu tun haben.

Dies kann z.B. folgendes sein:

* Löschen von Dateien im Dateisystem die während der Nutzung dieses Geräts angelegt worden sind.
* Lösen von evtl. Pairings mit dem physikalischen Gerät

Beispiel:
<syntaxhighlight lang="perl">
sub X_Delete($$)
{
my ( $hash, $name ) = @_;

# Löschen von Geräte-assoziiertem Temp-File
unlink($attr{global}{modpath}."/FHEM/FhemUtils/$name.tmp";)

return undef;
}
</syntaxhighlight>

Sollten im Rahmen der Delete-Funktion Probleme festgestellt werden, die ein Löschen nicht zulassen, so ist als Funktionsrückgabewert eine entsprechende Fehlermeldung zurückzugeben. Nur die Delete-Funktion erfolgreich durchgeführt wurde, darf <code>undef</code> zurückgegeben werden. Nur dann wird eine Gerätedefinition von FHEM auch tatsächlich gelöscht. Sollte die Delete-Funktion eine Fehlermeldung zurückgeben, wird der Löschvorgang abgebrochen und das Gerät bleibt weiter in FHEM bestehen.

==== X_Get ====
<syntaxhighlight lang="perl">
sub X_Get ($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

...

return $result;
}
</syntaxhighlight>
Die Get-Funktion wird aufgerufen wenn der FHEM-Befehl <code>get</code> für eine Definition dieses Moduls ausgeführt wird. Mit <code>get</code> werden typischerweise Werte von einem Gerät abgefragt. In vielen Modulen wird auf diese Weise auch der Zugriff auf generierte Readings ermöglicht. Der Get-Funktion wird dabei der Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$opt</code> plus optional weiterer Parameter <code>@args</code> übergeben. Als Rückgabewert <code>$result</code> wird das Ergebnis des entsprechenden Befehls in Form einer Zeichenkette zurückgegeben. Der Rückgabewert <code>undef</code> hat hierbei keine besondere Bedeutung und wird behandelt wie eine leere Zeichenkette <code>""</code>.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Get($$@)
{
my ( $hash, $name, $opt, @args ) = @_;

return "\"get $name\" needs at least one argument" unless(defined($opt));

if($opt eq "status")
{
...
}
elsif($opt eq "power")
{
...
}
...
else
{
return "Unknown argument $opt, choose one of status power [...]";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Get-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Get-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>get ''<NAME>'' '''?'''</code>, welche durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB nicht die möglichen Get-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $opt choose one of status temperature humidity";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Get-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>temperature</code>
* <code>humidity</code>

Dies würde in folgenden, mögliche Get-Befehle für einen User resultieren:

* <code>get ''<NAME>'' status</code>
* <code>get ''<NAME>'' temperature</code>
* <code>get ''<NAME>'' humidity</code>
</ul>

Im weiteren Verlauf der Get-Funktion könnte man dann mit dem physischen Gerät kommunizieren und den gefragten Wert direkt abfragen und diesen als Return-Wert der Get-Funktion zurückgeben. Vielfach werden aber auch die vorhandenen Readings zurückgegeben.

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Get() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Get($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

==== X_Set ====
<syntaxhighlight lang="perl">
sub X_Set ($$@)
{
my ( $hash, $name, $cmd, @args ) = @_;

...

return $error;
return ($error, $skip_trigger);
}
</syntaxhighlight>

Die Set-Funktion ist das Gegenteil zur [[#X_Get|Get]]-Funktion. Sie ist dafür gedacht, Daten zum physischen Gerät zu schicken, bzw. entsprechende Aktionen im Gerät selber auszulösen. Ein Set-Befehl dient daher der direkten Steuerung des physikalischen Gerätes in dem es bspw. Zustände verändert (wie <code>on</code>/<code>off</code>). Der Set-Funktion wird dabei der Definitions-Hash <code>$hash</code>, der Definitionsname <code>$name</code>, sowie die Aufrufparameter <code>$cmd</code> und optional weitere Argumente <code>@args</code> übergeben. Als Rückgabewert <code>$error</code> kann eine Fehlermeldung in Form Zeichenkette zurückgegeben werden. Der Rückgabewert <code>undef</code> bedeutet hierbei, dass der Set-Befehl erfolgreich durchgeführt wurde. Eine Set-Funktion gibt daher nur im Fehlerfall eine Rückmeldung mit einer entsprechenden Fehlermeldung. Der Wert <code>undef</code> wird als "erfolgreich" interpretiert.

Standardmäßig wird jeder Set-Befehl, welcher erfolgreich ausgeführt wurde (<code>$error</code> ist <code>undef</code>), als Event getriggert um dies bspw. in einem FileLog festzuhalten. Dieses Verhalten kann optional unterbunden werden indem der optionale zweite Rückgabewert <code>$skip_trigger</code> auf <code>1</code> gesetzt wird. Damit wird das Generieren eines Events für das erfolgreich ausgeführte Set-Kommando unterbunden. Falls nicht gesetzt, wird ein Event erzeugt (<code>$cmd</code> mit sämtlichen <code>@args</code>).

Rückmeldungen (Fehler) von set-Befehlen sämtlicher Module, die im Rahmen der Ausführung eines getriggerten [[Notify]] auftreten, werden im FHEM Logfile festgehalten.

Falls nur interne Daten, die ausschließlich für das Modul relevant sind, gesetzt werden müssen, so sollte statt Set die [[#X_Attr|Attr]]-Funktion verwendet werden. Attribute werden bei Save-Config auch in der Fhem.cfg gesichert. Set-Befehle nicht, da sie nur zu Steuerungszwecken im laufenden Betrieb von FHEM dienen.

Eine Set-Funktion ist ähnlich aufgebaut wie die Get-Funktion, sie bekommt jedoch in der Regel weitere zusätzliche Parameter (<code>@args</code>) übergeben um Zustände zu setzen/ändern.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "status")
{
if($args[0] eq "up")
{
...
}
elsif($args[0] eq "down")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
elsif($cmd eq "power")
{
if($args[0] eq "on")
{
...
}
elsif($args[0] eq "off")
{
...
}
else
{
return "Unknown value $args[0] for $cmd, choose one of status power";
}
}
...
else
{
return "Unknown argument $cmd, choose one of status power";
}
}
</syntaxhighlight>

Wenn eine unbekannte Option an die Set-Funktion übergeben wird, so muss als Rückgabewert der Funktion eine bestimmte Syntax eingehalten werden um FHEM mitzuteilen, welche Optionen für einen Set-Befehl aktuell unterstützt werden. Dies gilt insbesondere für den Aufruf <code>set ''<NAME>'' '''?'''</code>, welcher durch verschiedene Module (z.B. FHEMWEB) benutzt wird, um eine Liste aller unterstützten Befehle für eine Definition zu ermitteln. Die Rückgabe muss dabei folgender Syntax entsprechen:

<code>'''unknown''' argument ''[Parameter]'' '''choose one of''' ''[Liste möglicher Optionen]''</code>

Hierbei sind die fett gedruckten Teile der Rückmeldung besonders wichtig. Sind diese nicht vorhanden, können Module wie FHEMWEB nicht die möglichen Set-Kommandos für das entsprechende Gerät ermitteln. Es muss am Anfang der Meldung das Stichwort "unknown" vorkommen gefolgt von einer frei definierbaren Fehlermeldung (i.d.R der übergebene Parameter, welcher ungültig ist). Anschließend folgt "choose one of" mit einer anschließenden Liste möglicher Optionen getrennt durch ein Leerzeichen.

Beispiel:
<ul>
<syntaxhighlight lang="perl">return "unknown argument $cmd choose one of status power";</syntaxhighlight>

Hier werden als mögliche Optionen für einen Set-Befehl folgende Parameter angegeben:

* <code>status</code>
* <code>power</code>

Dies würde in folgenden, mögliche Set-Befehle für einen User resultieren:

* <code>set ''<NAME>'' status</code>
* <code>set ''<NAME>'' power</code>
</ul>

Nutzung von SetExtensions.pm

Wenn man dem Nutzer zusätzlich zu den Set-Befehlen <code>on</code> und <code>off</code> auch weiterführende Befehle wie <code>on-for-timer</code>, <code>on-till</code>, usw. anbieten möchte, obwohl die zu steuernde Hardware solche Kommandos nicht unterstützt, kann man dies über das Hilfsmodul SetExtensions.pm realisieren.

Das Hilfsmodul SetExtensions.pm bietet weiterführende Set-Kommandos basierend auf den Befehlen <code>on</code>/<code>off</code> an. Dabei werden durch interne Timer bzw. eigens angelegten [[at]]-Definitionen diese Befehle durch FHEM selber umgesetzt. Je nach ausgeführtem Befehl wird der <code>on</code>- bzw. <code>off</code>-Befehl dann durch FHEM zum richtigen Zeitpunkt ausgeführt. Vorausgesetzt das Modul unterstützt in der Set-Funktion die Befehle <code>on</code> und <code>off</code>, so werden durch den Einsatz von SetExtensions.pm folgende Befehle zusätzlich unterstützt:

{| class="wikitable"
|-
! Set-Kommando !! Beispiel !! Beschreibung
|-
| style="white-space: nowrap;" | <code>on-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>on-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und nach der angegebenen Dauer in Sekunden via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-for-timer ''<Dauer>''</code> || style="white-space: nowrap;" | <code>off-for-timer 120</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und nach der angegebenen Dauer in Sekunden via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>on</code>-Befehl ein und zum angegebenen Zeitpunkt via <code>off</code> wieder aus.
|-
| style="white-space: nowrap;" | <code>off-till ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till 16:30</code> || Schaltet das Gerät sofort mit dem <code>off</code>-Befehl aus und zum angegebenen Zeitpunkt via <code>on</code> wieder ein.
|-
| style="white-space: nowrap;" | <code>on-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>on-till-overnight 01:00</code> || Ähnlich wie <code>on-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>off-till-overnight ''<Zeitpunkt>''</code> || style="white-space: nowrap;" | <code>off-till-overnight 01:00</code> || Ähnlich wie <code>off-till</code>. Der übergebene Zeitpunkt wird aber nicht geprüft, ob er für den heutigen Tag bereits überschritten wurde. Dadurch kann man Abends einen Zeitpunkt setzen, der erst am nächsten Tag zutrifft.
|-
| style="white-space: nowrap;" | <code>blink ''<Anzahl> <Interval>''</code> || style="white-space: nowrap;" | <code>blink 3 1</code> || Schaltet das Gerät via <code>on</code> für <code>''<Interval>''</code> Sekunden ein und anschließend via <code>off</code> wieder aus. Nach <code>''<Interval>''</code> Sekunden wird das ganze wiederholt, solange bis die angegebene Anzahl erreicht ist.
|-
| style="white-space: nowrap;" | <code>intervals ''<Start>-<Ende>'' ''<Start>-<Ende>'' ...</code> || style="white-space: nowrap;" | <code>intervals 07:00-08:00 16:30-18:00</code> || Schaltet das Gerät innerhalb der übergebenen Zeiträumen via <code>on</code> ein. Sobald die aktuelle Zeit ausserhalb dieser Zeiträume liegt, wird das Gerät via <code>off</code> wieder ausgeschaltet. Es können dabei beliebig viele Zeiträume angegeben werden.
|-
| style="white-space: nowrap;" | <code>toggle</code> || style="white-space: nowrap;" | <code>toggle</code> || Sofern der aktuelle Status <code>on</code> ist, wird das Gerät via <code>off</code> ausgeschaltet. Andernfalls wird es via <code>on</code> eingeschaltet.
|}

Eine kurze Beschreibung zu den möglichen Befehlen durch SetExtensions.pm gibt es auch in der commandref zum {{Link2CmdRef|Anker=set|Label=set-Befehl}}.

Um SetExtensions.pm in der Set-Funktion nutzen zu können müssen folgende Aktionen durchgeführt werden:

# Laden von SetExtensions.pm via <code>use SetExtensions;</code> am Anfang des Moduls
# Aufruf und Rückgabe der Funktion [[DevelopmentModuleAPI#SetExtensions|SetExtensions()]] sofern die Set-Funktion mit dem übergebenen Befehl nichts anfangen kann.

Beispiel:

<syntaxhighlight lang="perl">
use SetExtensions;

...

sub X_Set($@)
{
my ( $hash, $name, $cmd, @args ) = @_;
my $cmdList = "on off";

return "\"set $name\" needs at least one argument" unless(defined($cmd));

if($cmd eq "on")
{
# Gerät einschalten...
}
elsif($cmd eq "off")
{
# Gerät ausschalten...
}
...
else # wenn der übergebene Befehl nicht durch X_Set() verarbeitet werden kann, Weitergabe an SetExtensions()
{
return SetExtensions($hash, $cmdList, $name, $cmd, @args);
}
}
</syntaxhighlight>

Sollte der übergebene Set-Befehl auch für SetExtensions unbekannt sein (bspw. <code>set ''<Name>'' ?</code>), so generiert SetExtensions() eine entsprechende Usage-Meldung, welche innerhalb der Set-Funktion an FHEM zurückgegeben werden muss.

Eine ausführliche Beschreibung zu der Funktion SetExtensions() gibt es in der [[DevelopmentModuleAPI#SetExtensions|API-Referenz]].

Nutzung von parseParams()

Wenn in [[#X_Initialize|X_Initialize()]] <code>$hash->{parseParams} = 1;</code> gesetzt wurde dann wird [[DevelopmentModuleAPI#parseParams|parseParams()]] automatisch aufgerufen und X_Set() ändert sich wie folgt:
<syntaxhighlight lang="perl">
sub X_Set($$$)
{
my ( $hash, $a, $h ) = @_;
...
</syntaxhighlight>

Die genauen Möglichkeiten von parseParams() sind in dem entsprechenden [[DevelopmentModuleAPI#parseParams|Artikel]] dokumentiert.

Nutzung von FHEMWEB-Widgets

Das GUI-Modul [[FHEMWEB]] kann für die einzelnen Set-Optionen, die das Modul versteht, automatisch Eingabehilfen wie Drop-Down Boxen oder Slider erzeugen. In der Detailansicht der GUI kann der Anwender dann die jeweiligen Werte komfortabel auswählen. Dafür muss die Set-Funktion, wenn sie mit der Option <code>?</code> aufgerufen wird, nicht nur einen Text mit <code>"Unknown ... choose one of ..."</code> zurückgeben sondern den einzelnen Set-Optionen in diesem Rückgabetext nach einem Doppelpunkt entsprechende Zusatzinformationen anhängen.
Meist prüft man in den Modulen gar nicht auf die Option <code>?</code> sondern gibt generell bei unbekannten Optionen diesen Text zurück. Das Modul FHEMWEB ermittelt die Syntax eines Gerätes jedoch immer mit dem Befehl:
set ''<NAME>'' ?

Beispiel:
<syntaxhighlight lang="perl">
return "Unknown argument $cmd, choose one of status:up,down power:on,off on:noArg off:noArg";
</syntaxhighlight>

Mit Kommata getrennte Werte ergeben eine Drop-Down Liste, mit der der User die Werte auswählen kann
<pre>timer:30,120,300
mode:verbose,ultra,relaxed</pre>

Wird kein Doppelpunkt zum Kommando angegeben, so wird eine Eingabezeile angezeigt, die die freie Eingabe eines Wertes erlaubt.

Man kann jedoch die Eingabe-/Auswahlmöglichkeiten durch Widgets vereinfachen. Dazu gibt man hinter dem Doppelpunkt einen Widgetnamen und widgetspezifische Parameter an. Es existieren mehrere solcher Widgets in FHEMWEB. Die gebräuchlichsten sind:

{| class="wikitable"
|-
! Zusatz !! Beispiel !! Beschreibung
|-
| '''noArg''' || <code>reset:noArg</code>|| Es werden keine weiteren Argumente mehr benötigt. In so einem Fall wird bei der Auswahl keine Textbox oder ähnliches angezeigt, da keine weiteren Argumente für diesen Befehl notwendig sind.
|-
| '''slider''',<min>,<step>,<max> || <code>dim:slider,0,1,100</code>|| Es wird ein Schieberegler angezeigt um den Parameter auszuwählen. Dabei werden als Zusatzparameter Minimum, Schrittweite und Maximum angegeben.
|-
| '''colorpicker''' || <code>rgb:colorpicker,RGB</code>|| Es wird ein Colorpicker angezeigt, der dem Anwender die Auswahl einer Farbe ermöglicht. Die genaue Parametersyntax kann man dem Artikel zum [[Color#Colorpicker|Colorpicker]] entnehmen.
|-
| '''multiple''' || <code>group:multiple,Telefon,Multimedia,Licht,Heizung</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte durch klicken auswählen kann. Optional kann man in einem Freitext eigene Werte ergänzen. dieser Dialog wird bspw. bei der Raum-Auswahl (Attribut "room") oder der Gruppen-Auswahl (Attribut "group") in FHEMWEB genutzt.
|-
| '''sortable''' || <code>command:sortable,monday,tuesday,...</code> || Es erscheint ein Auswahldialog, wo man verschiedene Werte auswählen und sortieren kann. Man kann dabei Werte durch Klicken auswählen und durch Drag'n'Drop sortieren.
|}

Es gibt noch weitere solcher Widgets. Eine genaue Auflistung dazu findet sich in der {{Link2CmdRef|Anker=widgetOverride}} unter widgetOverride zu FHEMWEB.

'''Hinweise'''

* Damit in einer Eingabe bereits der aktuelle Wert vorbelegt bzw. in einer Auswahlliste der aktuelle Wert vorselektiert ist, muss es im Modul bzw. Gerät ein Reading mit dem gleichen Namen wie die Set-Option geben. Der Wert des gleichnamigen Readings wird dann als Vorbelegung / Vorselektion verwendet.
* Der User kann sich in der Raumübersicht nach wie vor via [[WebCmd|webCmd]] eine entsprechende Steuerung anlegen.

==== X_Attr ====
<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Attr-Funktion dient der Prüfung von Attributen, welche über den <code>attr</code>-Befehl gesetzt werden können. Sobald versucht wird, ein Attribut für ein Gerät zu setzen, wird vorher die Attr-Funktion des entsprechenden Moduls aufgerufen um zu prüfen, ob das Attribut aus Sicht des Moduls korrekt ist.
Liegt ein Problem mit dem Attribut bzw. dem Wert vor, so muss die Funktion eine aussagekräftige Fehlermeldung zurückgeben, welche dem User angezeigt wird.
Sofern das übergebene Attribut samt Inhalt korrekt ist, gibt die Attr-Funktion den Wert <code>undef</code> zurück. Erst dann wird das Attribut in der globalen Datenstruktur <code>%attr</code> gespeichert und ist somit erst aktiv.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Attr($$$$)
{
my ( $cmd, $name, $attrName, $attrValue ) = @_;

# $cmd - Vorgangsart - kann die Werte "del" (löschen) oder "set" (setzen) annehmen
# $name - Gerätename
# $attrName/$attrValue sind Attribut-Name und Attribut-Wert

if ($cmd eq "set") {
if ($aName eq "Regex") {
eval { qr/$aVal/ };
if ($@) {
Log3 $name, 3, "X ($name) - Invalid regex in attr $name $aName $aVal: $@";
return "Invalid Regex $aVal: $@";
}
}
}
return undef;
}
</syntaxhighlight>

Zusätzlich ist es möglich auch übergebene Attributwerte zu verändern bzw. zu korrigieren, indem man im Parameterarray <code>@_</code> den ursprünglichen Wert anpasst. Dies erfolgt im Beispiel über die Modifikation des Wertes mit Index 3 (entspricht dem 4. Element) im Parameterarray, also <code>$_[3]</code>.

Da das Attribut zum Zeitpunkt des Aufrufs der Attr-Funktion noch nicht gespeichert ist, wird der neue Wert zu diesem Zeitpunkt noch nicht via [[DevelopmentModuleAPI#AttrVal|AttrVal()]] zurückgegeben. Erst, wenn die Attr-Funktion mit <code>undef</code> beendet ist, wird der neue Wert in FHEM gespeichert und steht dann via AttrVal() zur Verfügung.

Die Attr-Funktion bekommt nicht den Hash der Geräteinstanz übergeben, da sie normalerweise keine Werte dort speichern muss, sondern lediglich das Attribut auf Korrektheit prüfen muss.
Im obigen Beispiel wird für ein Attribut mit Namen "Regex" geprüft ob der reguläre Ausdruck fehlerhaft ist. Sofern dieser OK ist, wird <code>undef</code> zurückgegeben und fhem.pl speichert den Wert des Attributs in <code>%attr</code>.

Attributnamen mit Platzhaltern

Falls man Attribute in der [[#X_Initialize|Initialize]]-Funktion mit Platzhaltern definiert (Wildcard-Attribute) wie z.B.:
<syntaxhighlight lang="perl">
$hash->{AttrList} =
"reading[0-9]*Name " .
# usw.
</syntaxhighlight>
dann können Anwender Attribute wie reading01Name, reading02Name etc. setzen. Leider funktioniert das bisher nicht durch Klicken in der Web-Oberfläche, da FHEMWEB nicht alle denkbaren Ausprägungen in einem Dropdown anbieten kann. Der Benutzer muss solche Attribute manuell über den <code>attr</code>-Befehl eingeben.

Man kann jedoch in der Attr-Funktion neu gesetzte Ausprägungen von Wildcard-Attributen an die gerätespezifische userattr-Variable anfügen. Dann können bereits gesetzte Attribute in FHEMWEB durch Klicken ausgewählt und geändert werden.
Dazu reicht ein Aufruf der Funktion [[DevelopmentModuleAPI#addToDevAttrList|addToDevAttrList()]]:

<syntaxhighlight lang="perl">
addToDevAttrList($name, $aName);
</syntaxhighlight>

==== X_Read ====
<syntaxhighlight lang="perl">
sub X_Read ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Die X_Read-Funktion wird aufgerufen, wenn ein dem Gerät zugeordneter Filedeskriptor (serielle Schnittstelle, TCP-Verbindung, ...) Daten zum Lesen bereitgestellt hat. Die Daten müssen nun eingelesen und interpretiert werden.

Im folgenden Beispiel wird über eine serielle Schnittstelle (beziehungsweise über einen USB-To-Serial-Konverter) von einem angeschlossenen Gerät gelesen. Dazu werden die bisher verfügbaren Daten mit der Funktion [[DevIo#DevIo_SimpleRead()|DevIo_SimpleRead()]] gelesen. Da die Übertragung möglicherweise noch nicht vollständig ist, kann es sein, dass kurz darauf die X_Read-Funktion wieder aufgerufen wird und ein weiterer Teil oder der Rest der Daten gelesen werden kann.
Die Funktion muss daher prüfen ob schon alle erwarteten Daten angekommen sind und gegebenenfalls die bisher gelesenen Daten in einem eigenen Puffer (idealerweise in <code>$hash</code>) zwischenspeichern (siehe auch [[DevIo#Hinweis bei der Datenverarbeitung (Buffering)|DevIo]]). Im Beispiel ist dies <code>$hash->{helper}{BUFFER}</code> an den die aktuell gelesenen Daten angehängt werden, bis die folgende Prüfung ein für das jeweilige Protokoll vollständige Frame erkennt.

<syntaxhighlight lang="perl">
sub X_Read($)
{
my ($hash) = @_;
my $name = $hash->{NAME};

# einlesen der bereitstehenden Daten
my $buf = DevIo_SimpleRead($hash);
return "" if ( !defined($buf) );
Log3 $name, 5, "X ($name) - received data: ".$buf;

# Daten in Hex konvertieren und an den Puffer anhängen
$hash->{helper}{BUFFER} .= unpack ('H*', $buf);
Log3 $name, 5, "X ($name) - current buffer content: ".$hash->{helper}{BUFFER};

# prüfen, ob im Buffer ein vollständiger Frame zur Verarbeitung vorhanden ist.
if ($hash->{helper}{BUFFER} =~ "ff1002(.{4})(.*)1003(.{4})ff(.*)") {
...
</syntaxhighlight>

Die zu lesenden Nutzdaten können dann je nach Protokoll des Geräts beispielsweise an einer festgelegten Stelle im Frame (dann in <code>$hash->{helper}{BUFFER}</code>) stehen oder aus dem Kontext mit einem Regex-Match extrahiert werden und via [[DevelopmentModuleAPI#Readings_.2F_Events|Reading-Funktionen]] in Readings gespeichert werden (siehe unten).

Der Rückgabewert der Read-Funktion wird nicht geprüft und hat daher keinerlei Bedeutung.

==== X_Ready ====
<syntaxhighlight lang="perl">
sub X_Ready ($)
{
my ( $hash ) = @_;

...

return $success;
}
</syntaxhighlight>

Wird im Main-Loop aufgerufen falls das Modul in der globalen Liste <code>%readyfnlist</code> existiert. Diese Funktion hat, je nachdem auf welchem OS FHEM ausgeführt wird, unterschiedliche Aufgaben:

* '''UNIX-artiges Betriebssystem:''' prüfen, ob eine Verbindung nach einem Verbindungsabbruch wieder aufgebaut werden kann. Sobald der Verbindungsaufbau erfolgreich war, muss die Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1") und den eigenen Eintrag entsprechend aus <code>%readyfnlist</code> löschen.
* '''Windows-Betriebssystem:''' prüfen, ob lesbare Daten für ein serielles Device (via COM1, COM2, ...) vorliegen. Sofern lesbare Daten vorliegen, muss Funktion einen erfolgreichen Wahrheitswert zurückliefern (z.B. "1"). Zusätzlich dazu muss die Funktion, wie bei UNIX-artigen Betriebssystem, ebenfalls bei einem Verbindungsabbruch einen neuen Verbindungsversuch initiieren. Der Eintrag in <code>%readyfnlist</code> bleibt solange erhalten, bis die Verbindung seitens FHEM beendet wird.

Der Windows-spezifische Teil zur Datenprüfung ist dabei nur zu implementieren, wenn das Modul über eine serielle Verbindung kommuniziert.

Bei der Nutzung des Moduls [[DevIo]] wird dem Modulentwickler der Umgang mit <code>%readyfnlist</code> abgenommen, da DevIo sich selbst um die entsprechenden Einträge kümmert und diese selbstständig wieder entfernt.

In der Regel sieht eine Ready-Funktion immer gleich aus.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Ready($)
{
my ($hash) = @_;

# Versuch eines Verbindungsaufbaus, sofern die Verbindung beendet ist.
return DevIo_OpenDev($hash, 1, undef ) if ( $hash->{STATE} eq "disconnected" );

# This is relevant for Windows/USB only
if(defined($hash->{USBDev})) {
my $po = $hash->{USBDev};
my ( $BlockingFlags, $InBytes, $OutBytes, $ErrorFlags ) = $po->status;
return ( $InBytes > 0 );
}
}
</syntaxhighlight>

==== X_Notify ====

Die X_Notify-Funktion wird aus der Funktion [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] in fhem.pl heraus aufgerufen sobald ein Modul Events erzeugt hat. Damit kann ein Modul auf Events anderer Module reagieren. Typische Beispiele sind dabei das [[FileLog]]-Modul oder das [[notify]]-Modul.

Die Notify-Funktion bekommt dafür zwei Hash-Referenzen übergeben: den Hash des eigenen Geräts und den Hash des Geräts, das die Events erzeugt hat.
Über den Hash des eigenen Geräts kann die Notify-Funktion beispielsweise auf die Internals oder Attribute des eigenen Geräts zugreifen.
Über den Hash des Gerätes und der [[DevelopmentModuleAPI#deviceEvents|deviceEvents()]]-Funktion kann man auf die generierten Events zugreifen. Über den zweiten Parameter dieser Routine lässt sich bestimmen ob für das Reading <code>state</code> ein 'normales' Event (d.h. in der form <code>state: <wert></code>) erzeugen soll (Wert: 1) oder ob z.b. aus Gründen der Rückwärtskompatibilität ein Event ohne <code>state: </code> erzeugt werden soll. Falls dem Anwender die Wahl des verwendeten Formats überlassen werden soll ist hierzu das {{Link2CmdRef|Anker=addStateEvent|Lang=de|Label=addStateEvent-Attribut}} vorzusehen.

Der direkte Zugriff auf <code>$hash->{CHANGED}</code> ist nicht mehr zu empfehlen.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Notify($$)
{
my ($own_hash, $dev_hash) = @_;
my $ownName = $own_hash->{NAME}; # own name / hash

return "" if(IsDisabled($ownName)); # Return without any further action if the module is disabled

my $devName = $dev_hash->{NAME}; # Device that created the events

my $events = deviceEvents($dev_hash,1);
return if( !$events );

foreach my $event (@{$events}) {
$event = "" if(!defined($event));

# Examples:
# $event = "readingname: value"
# or
# $event = "INITIALIZED" (for $devName equal "global")
#
# processing $event with further code
}
}
</syntaxhighlight>

Begrenzung der Aufrufe auf bestimmte Geräte

Da die Notify-Funktion für jedes definierte Gerät mit all seinen Events aufgerufen wird, muss sie in einer Schleife jedesmal prüfen und entscheiden, ob es mit dem jeweiligen Event etwas anfangen kann. Ein Gerät, das die Notify-Funktion implementiert, sieht dafür typischerweise einen regulären Ausdruck vor, welcher für die Filterung verwendet wird.

Wenn man nur gezielt von bestimmten Definitionen Events erhalten will, kann man diese auch in Form einer {{Link2CmdRef|Lang=de|Anker=devspec|Label=devspec}} in <code>$hash->{NOTIFYDEV}</code> angeben. Bspw. kann man in der Define-Funktion diesen Wert setzen. Dadurch wird die Notify-Funktion nur aufgerufen wenn eine der Definitionen, auf welche die devspec passt, ein Event erzeugt hat. Ein typischer Fall ist die Begrenzung von Events auf "global":

<syntaxhighlight lang="perl">
in der Define-Funktion:

$hash->{NOTIFYDEV} = "global";
$hash->{NOTIFYDEV} = "global,Definition_.*";
$hash->{NOTIFYDEV} = "global,Definition_A,Definition_B";
$hash->{NOTIFYDEV} = "global,TYPE=CUL_HM";
</syntaxhighlight>

Dies schont insbesondere bei grossen Installationen Ressourcen, da die Notify-Funktion nicht sämtliche Events, sondern nur noch Events der gewünschten Definitionen erhält. Dadurch erfolgen deutlich weniger Aufrufe der Notify-Funktion, was Systemressourcen schont.

Sofern in der [[#X_Define|Define-Funktion]] eine Regexp als Argument übergeben wird, die ähnlich wie beim Modul [[notify]] auf Events wie <code><Definitionsname></code> bzw. <code><Definitionsname>:<Event></code> reagiert, so sollte man in der Define-Funktion die Funktion [[DevelopmentModuleAPI#notifyRegexpChanged|notifyRegexpChanged()]] verwenden. Diese versucht einen passenden Eintrag für <code>$hash->{NOTIFYDEV}</code> basierend auf der übergebenen Regexp zu setzen, sofern dies möglich ist.

Reihenfolge für den Aufruf der Notify-Funktion beeinflussen

Sobald ein Event ausgelöst wurde, stellt sich FHEM eine Liste aller relevanten Geräte-Hashes zusammen, welche via Notify-Funktion prüfen müssen, ob das Event relevant ist. Dabei wird die Liste nach <code>$hash->{NTFY_ORDER}</code> sortiert. Diese enthält ein Order-Präfix in Form einer Ganzzahl, sowie den Namen der Definition (Bsp: <code>'''50'''-Lampe_Wohnzimmer</code>). Dadurch kann man jedoch nicht sicherstellen, dass Events von bestimmten Modulen zuerst verarbeitet werden.

Wenn das eigene Modul bei der Eventverarbeitung gegenüber den anderen Modulen eine bestimmte Reihenfolge einhalten muss, kann man in der [[#X_Initialize|Initialize]]-Funktion durch Setzen von <code>$hash->{NotifyOrderPrefix}</code> diese Reihenfolge beeinflussen. Standardmäßig werden Module immer mit einem Order-Präfix von "50-" in FHEM registriert. Durch die Veränderung dieses Präfixes kann man das eigene Modul in der Reihenfolge gegenüber anderen Modulen bei der Eventverarbeitung beeinflussen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{NotifyOrderPrefix} = "45-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung zuerst geprüft

# oder...

$hash->{NotifyOrderPrefix} = "55-" # Alle Definitionen des Moduls X werden bei der Eventverarbeitung als letztes geprüft

</syntaxhighlight>

Da dieses Präfix bei eventverarbeitenden Definitionen in <code>$hash->{NTFY_ORDER}</code> dem Definitionsnamen vorangestellt wird bewirkt es bei einer normalen aufsteigenden Sortierung nach <code>$hash->{NTFY_ORDER}</code> eine veränderte Reihenfolge. Alle Module die in der Initialize-Funktion nicht <code>$hash->{NotifyOrderPrefix}</code> explizit setzen, werden mit "50-" als Standardwert vorbelegt.

==== X_Rename ====
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name) = @_;

...
}
</syntaxhighlight>

Die Rename-Funktion wird ausgeführt, nachdem ein Gerät umbenannt wurde. Auf diese Weise kann ein Modul auf eine Namensänderung reagieren, wenn das Gerät <code>$old_name</code> in <code>$new_name</code> umbenannt wurde. Ein typischer Fall ist das Umsetzen der Namensänderungen bei Daten die mittels [[DevelopmentModuleAPI#setKeyValue|setKeyValue()]] gespeichert wurden. Hierbei müssen die Daten, welche unter dem alten Namen gespeichert sind, auf den neuen Namen geändert werden.

Der Rename-Funktion wird lediglich der alte, sowie der neue Gerätename übergeben. Der Rückgabewert wird nicht ausgewertet.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Rename($$)
{
my ( $new_name, $old_name ) = @_;

my $old_index = "Module_X_".$old_name."_data";
my $new_index = "Module_X_".$new_name."_data";

my ($err, $data) = getKeyValue($old_index);
return undef unless(defined($old_pwd));

setKeyValue($new_index, $data);
setKeyValue($old_index, undef);
}
</syntaxhighlight>

==== X_DelayedShutdown ====
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ( $hash ) = @_;

...

return $delay_needed;
}
</syntaxhighlight>
Mit der X_DelayedShutdown Funktion kann eine Definition das Stoppen von FHEM verzögern um asynchron hinter sich aufzuräumen. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.), welcher mehrfache Requests/Responses benötigt. Als Übergabeparameter wird der Geräte-Hash <code>$hash</code> bereitgestellt. Je nach Rückgabewert <code>$delay_needed</code> wird der Stopp von FHEM verzögert. Ist ein verzögerter Stopp von FHEM notwendig, darf der Rückgabewert in diesem Fall nicht <code>0</code> oder <code>undef</code> sein.

Im Unterschied zur [[#X_Shutdown|Shutdown]]-Funktion steht vor einem bevorstehenden Stopp von FHEM für einen User-konfigurierbaren Zeitraum (global-Attribut: <code>maxShutdownDelay</code> / Standard: 10 Sekunden) weiterhin die asynchrone FHEM Infrastruktur ([[DevIo]]/[[#X_Read|Read]]-Funktion und [[DevelopmentModuleAPI#InternalTimer|InternalTimer]]) zur Verfügung.

Sobald alle nötigen Maßnahmen erledigt sind, muss der Abschluss mit [[DevelopmentModuleAPI#CancelDelayedShutdown|CancelDelayedShutdown(<code>$name</code>)]] an FHEM zurückgemeldet werden.

Beispiel:
<syntaxhighlight lang="perl">
sub X_DelayedShutdown($)
{
my ($hash) = @_;

# Aufräumen starten

return 1;
}
</syntaxhighlight>

==== X_Shutdown ====
<syntaxhighlight lang="perl">
sub X_Shutdown ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>
Mit der X_Shutdown Funktion kann ein Modul Aktionen durchführen bevor FHEM gestoppt wird. Dies kann z.B. der ordnungsgemäße Verbindungsabbau mit dem physikalischen Gerät sein (z.B. Session beenden, Logout, etc.). Nach der Ausführung der Shutdown-Fuktion wird FHEM sofort beendet. Falls vor dem Herunterfahren von FHEM asynchrone Kommunikation (via [[DevIo]]/[[#X_Read|X_Read]]) notwendig ist um eine vorhandene Verbindung sauber zu beenden, sollte man [[#X_DelayedShutdownFn|X_DelayedShutdownFn]] verwenden.

Als Übergabeparameter wird der Geräte-Hash bereitgestellt. Der Rückgabewert einer Shutdown-Funktion wird nicht ausgewertet und ist daher irrelevant.

Beispiel:
<syntaxhighlight lang="perl">
sub X_Shutdown($)
{
my ($hash) = @_;

# Verbindung schließen
DevIo_CloseDev($hash);
return undef;
}
</syntaxhighlight>

=== Funktionen für zweistufiges Modulkonzept ===

Für das [[#Zweistufiges_Modell_für_Module|zweistufige Modulkonzept]] gibt es weiterhin:

{| class="wikitable sortable"
|-
! style="text-align:left" | Funktionsname !! style="text-align:left" class="unsortable" | Kurzbeschreibung
|-
| [[#X_Parse|X_Parse]] || Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] vom physischen Modul zum logischen Modul zwecks der Verarbeitung.
|-
| [[#X_Write|X_Write]]|| Zustellen von Daten via [[DevelopmentModuleAPI#Dispatch|IOWrite()]] vom logischen zum physischen Modul um diese an die Hardware weiterzureichen.
|-
| [[#X_Fingerprint|X_Fingerprint]] || Rückgabe eines "Fingerabdrucks" einer Nachricht. Dient der Erkennung von Duplikaten im Rahmen von [[DevelopmentModuleAPI#Dispatch|Dispatch()]]. Kann im physischen, als auch logischen Modul benutzt werden.
|}

Für das zweistufige Modulkonzept muss in einem logischen Modul eine [[#X_Parse|Parse]]-Funktion im Modul-Hash registriert werden. In einem physikalischen Modul muss eine [[#X_Write|Write]]-Funktion registriert sein. Diese dienen dem Datenaustausch in beide Richtungen und werden von dem jeweils anderen Modul indirekt aufgerufen.

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{ParseFn} = "X_Parse";
$hash->{WriteFn} = "X_Write";
$hash->{FingerprintFn} = "X_Fingerprint";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.

==== X_Parse ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''logisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit einem übergeordneten, physikalischen Modul austauscht.}}
<syntaxhighlight lang="perl">
sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

...

return $found;
}
</syntaxhighlight>

Die Funktion X_Parse wird aufgerufen, sobald von dem IO-Gerät <code>$io_hash</code> eine Nachricht <code>$message</code> via [[DevelopmentModuleAPI#Dispatch|Dispatch()]] zur Verarbeitung angefragt wird. Die Parse-Funktion muss dann prüfen, zu welcher Gerätedefinition diese Nachricht gehört und diese entsprechend verarbeiten.

Üblicherweise enthält eine Nachricht immer eine Komponente durch welche sich die Nachricht einem Gerät zuordnen lässt (z.B. Adresse, ID-Nummer, ...). Eine solche Identifikation sollte man im Rahmen der [[#X_Define|Define]]-Funktion im logischen Modul an geeigneter Stelle speichern, um in der Parse-Funktion eine einfache Zuordnung von Adresse/ID einer Nachricht zur entsprechenden Gerätedefinition zu haben. Dazu wird in der Regel im Modul-Hash im modulspezifischen Bereich eine Liste <code>defptr</code> (Definition Pointer) geführt, welche jede eindeutige Adresse/ID dem entsprechenden Geräte-Hash zuordnet:

<syntaxhighlight lang="perl">

sub X_Define ($$)
{
my ( $hash, $def) = @_;
my @a = split("[ \t][ \t]*", $def);
my $name = $a[0];

...

# erstes Argument ist die eindeutige Geräteadresse
my $address = $a[1];

# Adresse rückwärts dem Hash zuordnen (für ParseFn)
$modules{X}{defptr}{$address} = $hash;

...
}
</syntaxhighlight>

Auf Basis dieses Definition Pointers kann die Parse-Funktion nun sehr einfach prüfen, ob für die empfangene Nachricht bereits eine entsprechende Gerätedefinition existiert. Sofern diese existiert, kann die Nachricht entsprechend verarbeitet werden. Sollte jedoch keine passende Gerätedefinition zu der empfangenen Nachricht existieren, so muss die Parse-Funktion den Gerätenamen "UNDEFINED" zusammen mit den Argumenten für einen <code>define</code>-Befehl zurückgeben, welcher ein passendes Gerät in FHEM anlegen würde (durch [[autocreate]]).

Beispiel:

<syntaxhighlight lang="perl">

sub X_Parse ($$)
{
my ( $io_hash, $message) = @_;

# Die Stellen 10-15 enthalten die eindeutige Identifikation des Geräts
my $address = substr($message, 10, 5);

# wenn bereits eine Gerätedefinition existiert (via Definition Pointer aus Define-Funktion)
if(my $hash = $modules{X}{defptr}{$address})
{
... # Nachricht für $hash verarbeiten

# Rückgabe des Gerätenamens, für welches die Nachricht bestimmt ist.
return $hash->{NAME};
}
else
{
# Keine Gerätedefinition verfügbar
# Daher Vorschlag define-Befehl: <NAME> <MODULNAME> <ADDRESSE>
return "UNDEFINED X_".$address." X $address";
}
}
</syntaxhighlight>

==== X_Write ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Dieser Abschnitt geht davon aus, dass das Modul mit dem Namen "X" ein '''physisches Modul''' im Sinne des zweistufigen Modulkonzepts ist, also Daten mit untergeordneten logischen Modulen austauscht. }}
<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, @arguments) = @_;

...

return $return;
}
</syntaxhighlight>

Die Write-Funktion wird durch die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] aufgerufen, sobald eine logische Gerätedefinition Daten per IO-Gerät an die Hardware übertragen möchte. Dazu kümmert sich die Write-Funktion um die Übertragung der Nachricht in geeigneter Form an die verbundene Hardware. Als Argumente wird der Hash des physischen Gerätes übertragen, sowie alle weiteren Argumente, die das logische Modul beim Aufruf von IOWrite() mitgegeben hat. Im Normalfall ist das ein Skalar mit der zu sendenden Nachricht in Textform. Es kann aber auch sein, dass weitere Daten zum Versand notwendig sind (evtl. Schlüssel, Session-Key, ...). Daher ist die Parametersyntax einer zu schreibenden Nachricht via IOWrite-/Write-Funktion zwischen logischem und physikalischem Modul abzustimmen.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Write ($$)
{
my ( $hash, $message, $address) = @_;

DevIo_SimpleWrite($hash, $address.$message, 2);

return undef;
}
</syntaxhighlight>

==== X_Fingerprint ====
<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

...

return ( $io_name, $fingerprint );
}
</syntaxhighlight>

Die Fingerprint-Funktion dient der Erkennung von Duplikaten empfangener Nachrichten. Diese Funktion kann dabei sowohl im physischen, als auch im logischen Modul implementiert sein - je nachdem auf welcher Ebene man für eine Nachricht einen Fingerprint bilden kann.

Als Parameter wird der Name des IO-Geräts <code>$io_name</code> übergeben, sowie die Nachricht <code>$msg</code>, welche empfangen wurde. Nun muss aus dieser Nachricht ein eindeutiger Fingerprint gebildet werden. Dies bedeutet, dass alle variablen Inhalte, die aufgrund des Empfangs dieser Nachricht über unterschiedliche IO-Geräte enthalten sein können, entfernt werden müssen. Dies können bspw. Empfangsadressen von IO-Geräten sein oder Session-ID's die in der Nachricht enthalten sind. Alle Fingerprints sämtlicher Nachrichten, die innerhalb der letzten 500 Millisekunden (konfigurierbar via <code>global</code> Attribut <code>dupTimeout</code>) empfangen wurden, werden gegen diesen generierten Fingerprint getestet. Sollte innerhalb dieser Zeit bereits eine Nachricht mit diesem Fingerprint verarbeitet worden sein, so wird sie als Duplikat erkannt und nicht weiter verarbeitet. In diesem Fall gibt [[DevelopmentModuleAPI#Dispatch|Dispatch()]] den Namen der Gerätedefinition zurück, welche eine Nachricht mit dem selben Fingerprint bereits verarbeitet hat. Es erfolgt dann kein Aufruf der [[#X_Parse|Parse]]-Funktion.

Beispiel:

<syntaxhighlight lang="perl">
sub X_Fingerprint($$)
{
my ( $io_name, $msg ) = @_;

substr( $msg, 2, 2, "--" ); # entferne Empfangsadresse
substr( $msg, 4, 1, "-" ); # entferne Hop-Count

return ( $io_name, $msg );
}
</syntaxhighlight>

Es wird zuerst, sofern implementiert, die Fingerprint-Funktion des physischen Moduls aufgerufen. Sollte sich hierdurch kein Duplikat erkennen lassen, wird die Fingerprint-Funktion jedes möglichen geladenen logischen Moduls aufgerufen, sofern implementiert.

Sollte sowohl im physischen, als auch im logischen Modul keine Fingerprint-Funktion implementiert sein, so wird keinerlei Duplikatserkennung durchgeführt.

=== FHEMWEB-spezifische Funktionen ===

FHEMWEB bietet Modul-Autoren die Möglichkeit an durch spezielle Funktionsaufrufe in Modulen, eigene HTML-Inhalte zu verwenden. Dadurch können in Verbindung mit zusätzlichem JavaScript komplexe Dialoge/Inhalte/Steuermöglichkeiten dargestellt werden.

Eine genaue Auflistung aller FHEMWEB-spezifischen Funktionsaufrufe gibt es in dem separaten Artikel [[DevelopmentFHEMWEB]]

=== sonstige Funktionen ===

In diesem Abschnitt werden weitere Funktionen behandelt die zum Teil aus FHEM, aber auch aus anderen Modulen aufgerufen werden. Sie sind dabei nur in speziellen Anwendungsfällen relevant. Hier eine Auflistung aller sonstigen Modulfunktionen:

{| class="wikitable sortable"
|-
! Funktionsname !! class="unsortable" | Kurzbeschreibung
|-
| [[#X_DbLog_split|X_DbLog_split]] || Wird durch das Modul 93_DbLog.pm aufgerufen. Dient dem korrekten Split eines moduleigenen Events in Name/Wert/Einheit für die Nutzung einer Datenbank.
|-
| [[#X_Except|X_Except]]|| Wird aufgerufen, sobald ein ein geöffneter Filedescriptor in [[#Wichtige_globale_Variablen_aus_fhem.pl|<code>%selectlist</code>]], der unter <code>$hash->{EXCEPT_FD}</code> im Geräte-Hash gesetzt ist, einen Interrupt bzw. Exception auslöst.
|-
| [[#X_Copy|X_Copy]]|| Wird durch das Modul 98_copy.pm aufgerufen im Rahmen des <code>copy</code>-Befehls sobald ein Gerät kopiert wurde.
|-
| [[#X_State|X_State]]|| Wird aufgerufen im Rahmen des <code>setstate</code>-Befehls bevor der Status einer Gerätedefinition bzw. eines zugehörigen Readings gesetzt wird.
|-
| [[#X_AsyncOutput|X_AsyncOutput]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht die asynchrone Ausgabe von Daten via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an einen einzelnen verbundenen Client.
|-
| [[#X_ActivateInform|X_ActivateInform]]|| Nur relevant für Module die via [[TcpServerUtils]] eine Client-Verbindung zu FHEM ermöglichen (z.B. FHEMWEB und telnet). Ermöglicht das Aktivieren des inform-Mechanismus zum Senden von Events für einen einzelnen verbundenen Client.
|-
| [[#X_Authorize|X_Authorize]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authorized|Authorized()]] um eine gewünschte Vorgangs-Art zu autorisieren.
|-
| [[#X_Authenticate|X_Authenticate]]|| Wird aufgerufen im Rahmen von [[DevelopmentModuleAPI#Authenticate|Authenticate()]] um eine Authentifizierung zu prüfen und ggf. zu genehmigen.
|}

In der [[#X_Initialize|Initialize]]-Funktion werden diese wie folgt definiert:

<syntaxhighlight lang="perl">
$hash->{DbLog_splitFn} = "X_DbLog_split";
$hash->{ExceptFn} = "X_Except";
$hash->{CopyFn} = "X_Copy";
$hash->{AsyncOutputFn} = "X_AsyncOutput";
$hash->{ActivateInformFn} = "X_ActivateInform";
$hash->{StateFn} = "X_State";
$hash->{AuthorizeFn} = "X_Authorize";
$hash->{AuthenticateFn} = "X_Authenticate";
</syntaxhighlight>

Diese Funktionen werden in diesem Abschnitt genauer beschrieben.
==== X_DbLog_split ====
<syntaxhighlight lang="perl">
sub X_DbLog_split ($$)
{
my ( $event, $device_name ) = @_;

...

return ( $reading, $value, $unit );
}
</syntaxhighlight>

Die DbLog_split-Funktion wird durch das Modul [[DbLog]] aufgerufen, sofern der Nutzer DbLog benutzt. Sofern diese Funktion implementiert ist, kann der Modul-Autor das Auftrennen von Events in den Reading-Namen, -Wert und der Einheit selbst steuern. Andernfalls nimmt DbLog diese Auftrennung selber mittels Trennung durch Leerzeichen sowie vordefinierten Regeln zu verschiedenen Modulen vor. Je nachdem, welche Readings man in seinem Modul implementiert, passt diese standardmäßige Trennung jedoch nicht immer.

Der Funktion werden folgende Eingangsparameter übergeben:
# Das generierte Event (Bsp: <code>temperature: 20.5 °C</code>)
# Der Name des Geräts, welche das Event erzeugt hat (Bsp: <code>Temperatursensor_Wohnzimmer</code>)

Es ist nicht möglich in der DbLog_split-Funktion auf die verarbeitende DbLog-Definition zu referenzieren.

Als Rückgabewerte muss die Funktion folgende Werte bereitstellen:
# Name des Readings (Bsp: <code>temperature</code>)
# Wert des Readings (Bsp: <code>20.5</code>)
# Einheit des Readings (Bsp: <code>°C</code>)

Beispiel:
<syntaxhighlight lang="perl">
sub X_DbLog_splitFn($$)
{
my ($event, $device) = @_;
my ($reading, $value, $unit);
my $devhash = $defs{$device}

if($event =~ m/temperature/) {
$reading = 'temperature';
$value = substr($event,12,4);
$unit = '°C';
}

return ($reading, $value, $unit);
}
</syntaxhighlight>

==== X_Except ====
<syntaxhighlight lang="perl">
sub X_Except ($)
{
my ( $hash ) = @_;

...
}
</syntaxhighlight>

Die X_Except-Funktion wird durch fhem.pl aufgerufen, wenn die Gerätedefinition <code>$hash</code> in <code>[[#Wichtige_globale_Variablen_aus_fhem.pl|%selectlist]]</code> aufgeführt ist und der Filedeskriptor in <code>$hash->{EXCEPT_FD}</code> eine Exception bzw. Interrupt auslöst.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">
use IO::File;

...

sub X_Except ($)
{
my ( $hash ) = @_;

# Filehandle aus Filedescriptor erstellen
my $filehandle = IO::File->new_from_fd($hash->{EXCEPT_FD}, 'r');
seek($filehandle,0,0);

# aktuellen Inhalt auslesen
my $current_value = $filehandle->getline;

if($current_value eq "1")
{
...
}
else
{
...
}
}
</syntaxhighlight>

==== X_Copy ====
<syntaxhighlight lang="perl">
sub X_Copy ($)
{
my ( $old_name, $new_name ) = @_;

...
}
</syntaxhighlight>

Die X_Copy-Funktion wird durch das Modul [[copy]] aufgerufen nachdem ein Nutzer eine Gerätedefinition über den Befehl <code>copy</code> kopiert hat. Dazu werden als Funktionsparameter die Definitionsnamen der alten und neuen Gerätedefinition übergeben. Es dient dazu zusätzliche Daten aus der zu kopierenden Gerätedefinition in die neue Definition zu übernehmen. Der Befehl <code>copy</code> überträgt lediglich <code>$hash->{DEF}</code> in die neue Definition sowie sämtliche gesetzte Attribute. Weitere Daten müssen dann durch die X_Copy-Funktion übertragen werden.

Die X_Copy-Funktion wird erst nach dem erfolgtem Kopiervorgang aufgerufen.

Der Rückgabewert wird nicht ausgewertet und ist daher irrelevant.

Beispiel:

<syntaxhighlight lang="perl">

sub X_Copy ($$)
{
my ( $old_name, $new_name ) = @_;

my $old_hash = $defs{$old_name};
my $new_hash = $defs{$new_name};

# copy also temporary session key
$new_hash->{helper}{SESSION_KEY} = $old_hash->{helper}{SESSION_KEY};
}
</syntaxhighlight>

==== X_AsyncOutput ====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_AsyncOutput ($)
{
my ( $client_hash, $text ) = @_;

...

return $error;
}
</syntaxhighlight>

Die Funktion X_AsyncOutput wird durch [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] von anderen Modulen aufgerufen. Es erlaubt diesen anderen Modulen die Ausgabe von asynchronen Befehlsergebnissen <code>$text</code> zuvor ausgeführter set-/get-Befehle an den entsprechenden Client (identifiziert durch den Client-Hash <code>$client_hash</code> der temporären Definition) zurückzugeben.

Wenn ein Client einen set-/get-Befehl ausführt, wird der Client-Hash bei der Ausführung dieser Befehle an die jeweiligen Module übermittelt. Sobald ein Befehl ausgeführt wird, der seine Ausgabe asynchron ausführen möchte und die Client-Verbindung des Server-Moduls dies unterstützt (<code>$client_hash->{canAsyncOutput}</code> ist gesetzt), merkt sich das befehlsausführende Modul den Client-Hash und gibt das Ergebnis des Befehls zu späterer Zeit via [[DevelopmentModuleAPI#asyncOutput|asyncOutput()]] an den ursprünglichen Client zurück. Die Funktion X_AsyncOutput des Server-Moduls kümmert sich darum das Ergebnis dem entsprechenden Client in der notwendigen Form zuzustellen.

Der Rückgabewert von X_AsyncOutput() wird als Rückgabewert für asyncOutput() verwendet. Man kann hier im Fehlerfall eine Fehlermeldung angeben und im Erfolgsfall <code>undef</code>. Der Rückgabewert wird aber aktuell nicht ausgewertet.

==== X_ActivateInform====
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG:''' Diese Funktion ist nur relevant, wenn man ein Frontend-Modul erstellt über das FHEM von einem Anwender bedient werden kann (FHEMWEB, telnet, yowsup, telegram, alexa-fhem, homebridge-fhem, tabletui, ...).}}
<syntaxhighlight lang="perl">
sub X_ActivateInform($$)
{
my ( $client_hash, $arg ) = @_;

...
}
</syntaxhighlight>

Die Funktion X_ActivateInform wird aktuell nur durch den [[update]]-Befehl aufgerufen, sofern ein Client eines Frontend-Moduls diesen Befehl aufgerufen hat um den Inform-Mechanismus (Senden von Events) zu aktivieren. Dadurch wird im Falle von [[update]] die umgehende Anzeige der Logmeldungen für den ausführenden Client aktiviert. In [[FHEMWEB]] geschieht das über den Event-Monitor, bei telnet mit der direkten Ausgabe.

Da diese Funktion aktuell nur speziell für den update-Befehl implementiert ist, kann man aktuell keine genaue Angaben zu den möglichen Werten von <code>$arg</code> geben. Dieser Parameter dient dazu genauer zu spezifizieren was exakt an Events an den entsprechenden Client <code>$client_hash</code> zu senden ist. Aktuell wird dazu die Parametersyntax des inform-Befehls verwendet (on|off|log|raw|timer|status).

==== X_State ====
<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

...

return $error;
}
</syntaxhighlight>

Die X_State-Funktion wird durch fhem.pl aufgerufen, sobald über den Befehl <code>setstate</code> versucht wird ein Wert für ein Reading oder den Status (<code>$hash->{STATE}</code>) einer Gerätedefinition zu setzen. Dieser Befehl wird primär beim Starten von FHEM aufgerufen sobald das State-File eingelesen wird. Je nachdem, ob im gegebenen Fall ein Reading oder der Definitionsstatus gesetzt wird, haben die Übergabeparameter verschiedene Werte:

{| class="wikitable"
|-
! Funktionsparameter!! Wert beim Setzen eines Readings !! Wert beim Setzen eines Definitionsstatus
|-
| <code>$hash</code> || colspan="2" align="center" | Die Hashreferenz der betreffenden Gerätedefinition
|-
| <code>$time</code>|| Der Zeitstempel auf welchen das Reading <code>$readingName</code> gesetzt werden soll. Das Ergebnis entspricht dem Rückgabewert der Funktion || Der aktuelle Zeitstempel zum jetzigen Zeitpunkt.
|-
| <code>$readingName</code>|| Der Name des Readings, welches auf einen neuen Wert gesetzt werden soll. || Statischer Wert "STATE" um anzuzeigen, dass es sich um den Definitionsstatus handelt, welcher gesetzt werden soll (<code>$hash->{STATE}</code>).
|-
| <code>$value</code> || Den Wert, welchen das Reading <code>$readingName</code> annehmen soll. || Den Wert, welchen die Gerätedefinition als Status annehmen soll.
|}

Wenn via <code>setstate</code> ein Reading gesetzt wird, kann die X_State-Funktion das Setzen dieses Readings durch die Rückgabe einer aussagekräftigen Fehlermeldung unterbinden. Sofern <code>undef</code> zurückgegeben wird, wird das entsprechende Reading auf den übergebenen Status gesetzt.

Wenn via <code>setstate</code> der Definitionsstatus gesetzt wird, wird die X_State-Funktion erst nach dem Setzen des Status aufgerufen. Man kann dabei zwar eine Fehlermeldung zurückgeben, der Status wird aber dennoch übernommen. Die Fehlermeldung wird lediglich dem Nutzer angezeigt.

Beispiel:

<syntaxhighlight lang="perl">
sub X_State($$$$)
{
my ( $hash, $time, $readingName, $value ) = @_;

return undef if($readingName "STATE" || $value ne "inactive");
readingsSingleUpdate($hash, "state", "inactive", 1);
return undef;
}
</syntaxhighlight>

==== X_Authorize ====
<syntaxhighlight lang="perl">
sub X_Authorize($$$$)
{
my ( $hash, $client_hash, $type, $arg ) = @_;

...

return $authorized;
}
</syntaxhighlight>

Die Authorize-Funktion wird von fhem.pl aufgerufen um zu erfragen, ob ein bestimmter Client <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf. Auf diese Weise können Module Einfluss nehmen, welcher User welche Funktionen in FHEM nutzen darf. Wenn ein Client eine Aktion ausführen möchte, werden alle Module, die eine Authorize-Funktion implementiert haben, gefragt, ob diese Aktion ausgeführt werden darf. Als Rückgabewert wird das Ergebnis der Überprüfung zurückgegeben, wobei <code>0</code> (unbekannt / nicht zuständig), <code>1</code> (erlaubt) oder <code>2</code> (verboten) zurückgegeben werden können.

Es gibt aktuell folgende <code>$type</code>/<code>$arg</code> Kombinationen, mit denen die Authorize-Funktion aufgerufen werden:

{| class="wikitable"
|-
! $type !! $arg !! Überschrift
|-
| rowspan="3" style="white-space: nowrap;" | <code>'''$type''' = "cmd"</code>

''Befehlsausführung''
| style="white-space: nowrap;" | <code>'''$arg''' = "set Lampe on"</code> || Jeglicher FHEM-Befehl, der ausgeführt werden soll, wird in <code>$arg</code> hinterlegt, sodass innerhalb einer Authorize-Funktion der Befehl genauer geparst werden kann um zu entscheiden, ob dieser Befehl erlaubt ist, oder nicht.
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "perl"</code> || Ausführen von Perl-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>{ReadingsVal("Lampe", "state", "off"}</code>
|-
| style="white-space: nowrap;" | <code>'''$arg''' = "shell"</code> || Ausführen von Shell-Befehlen jeglicher Art. Der genaue Befehl wird dabei nicht an die Authorize-Funktion übergeben.

Bsp: <code>"/opt/fhem/myScript.sh"</code>
|-
| style="white-space: nowrap;" | <code>'''$type''' = "devicename"</code>

''Sichtbarkeit von Geräten/Definitionen''
| style="white-space: nowrap;" | <code>'''$arg''' = "Licht_Wohnzimmer"</code> || Sichtbarkeit des jeweiligen Gerät/Definition in FHEM. Dies bedeutet konkret die Auffindbarkeit im <code>list</code>-Befehl, sowie der Suche via [[DevelopmentModuleAPI#devspec2array|devspec2array()]]. Wird eine solche Anfrage durch die Authorize-Funktion abgelehnt, ist das entsprechende Gerät bzw. Definition für den jeweiligen Client nicht sichtbar.
|}

==== X_Authenticate ====
{{Link2Forum|Topic=72757|Message=644098}}

== Bereitstellen eines eigenen Befehls (Befehlsmodul) ==

Ein Modul kann primär einen neuen FHEM-Befehl bereitstellen. Man spricht in so einem Fall nicht von einem Gerätemodul, sondern einem Befehlsmodul. Ein solches Befehlsmodul stellt nur einen einzelnen Befehl bereit, der dem Modulnamen entsprechen muss. Nur, wenn der Modulname dem Befehlsname entspricht, kann FHEM das Modul beim ersten Ausführen dieses unbekannten Befehls finden und nachladen.

Der entsprechende Befehl wird dazu in der [[#X_Initialize|Initialize]]-Funktion im globalen Hash <code>[[DevelopmentModuleIntro#Wichtige_globale_Variablen_aus_fhem.pl|%cmds]]</code> registriert:

<syntaxhighlight lang="perl">
sub X_Initialize($$) {

$cmds{X} = { Fn => "CommandX",
Hlp => "<argument1> [optional_argument2], print something very useful",

# optionaler Filter für Clientmodule als regulärer Ausdruck
ClientFilter => "FHEMWEB"
};
}
</syntaxhighlight>

Damit wird der neue Befehl <code>X</code> in FHEM registriert. Die Funktion mit dem Namen <code>CommandX</code> setzt diesen Befehl innerhalb des Moduls um. Desweiteren wird eine kurze Aufrufsyntax mitgegeben, welche beim Aufruf des <code>help</code>-Befehls dem Nutzer angezeigt wird um als Gedankenstütze zu dienen. Optional kann man mittels <code>ClientFilter</code> (regulärer Ausdruck für Modulnamen) die Ausführbarkeit nur auf bestimmte Client-Module (wie FHEMWEB oder telnet) beschränken.

Nun muss noch die Funktion <code>CommandX</code> im Rahmen des Moduls implementiert werden, welche den Befehl <code>X</code> umsetzt:

<syntaxhighlight lang="Perl">
sub CommandX($$)
{
my ($client_hash, $arguments) = @_;

...

return $output;
}
</syntaxhighlight>

Dabei werden der Befehlsfunktion zwei Parameter übergeben. Zuerst die Hash-Referenz des aufrufenden Clients (sofern manuell ausgeführt, ansonsten <code>undef</code>) zwecks Rechteprüfung via [[allowed|allowed-Definitionen]]. Anschließend folgen die Aufrufparameter als zusammenhängende Zeichenkette. Die Trennung der einzelnen Argumente obligt der Funktion (bspw. via [[DevelopmentModuleAPI#parseParams|parseParams()]]). Als Funktionsrückgabewert wird eine Ausgabemeldung erwartet, die dem Nutzer angezeigt werden soll.

== Pollen von Geräten ==
Wenn Geräte von sich aus keine Informationen senden sondern abgefragt werden müssen, kann man im Modul die Funktion [[DevelopmentModuleAPI#InternalTimer|InternalTimer()]] verwenden um einen Funktionsaufruf zu einem späteren Zeitpunkt durchführen zu können. Man übergibt dabei den Zeitpunkt für den nächsten Aufruf, den Namen der Funktion, die aufgerufen werden soll, sowie den zu übergebenden Parameter. Als zu übergebender Parameter wird üblicherweise der Hash der betroffenen Geräteinstanz verwendet. Damit hat die aufgerufene Funktion Zugriff auf alle wichtigen Daten der Geräteinstanz. Eventuell zusätzlich benötigte Werte können einfach als weitere Internals über den Hash zugänglich gemacht werden.

Beispielsweise könnte man für das Abfragen eines Geräts in der [[#X_Define|Define]]-Funktion den Timer folgendermaßen setzen:

<syntaxhighlight lang="perl">
InternalTimer(gettimeofday()+2, "X_GetUpdate", $hash);
</syntaxhighlight>

Alternativ kann man auch in der [[#X_Notify|Notify]]-Funktion auf das Event <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code> reagieren und erst dort, den Timer anstoßen, sobald die Konfiguration komplett eingelesen wurde. Dies ist insbesondere notwendig, wenn man sicherstellen will, dass alle Attribute aus der Konfiguration gesetzt sind, sobald man einen Status-Update initiiert.

In der Funktion <code>X_GetUpdate</code> selbst wird dann der Timer neu gesetzt, so dass nach einem Intervall die Funktion erneut aufgerufen wird:

<syntaxhighlight lang="perl">
sub X_GetUpdate($)
{
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 4, "X: GetUpdate called ...";

...

# neuen Timer starten in einem konfigurierten Interval.
InternalTimer(gettimeofday()+$hash->{Interval}, "X_GetUpdate", $hash);
}
</syntaxhighlight>

Innerhalb der Funktion kann man nun das Gerät abfragen und die abgefragten Werte in Readings speichern. Falls das Abfragen der Werte jedoch zu einer Verzögerung und damit zu einer Blockade von FHEM führen kann, ist es möglich, in der GetUpdate-Funktion nur die Aufforderung zum Senden bestimmter Daten an das angeschlossene Gerät zu senden und dann das Lesen über die oben beschriebene [[#X_Read|Read]]-Funktion zu implementieren.

Eine genaue Beschreibung der Timer-Funktion gibt es [[DevelopmentModuleAPI#Timer|hier im Wiki]]

== Logging / Debugging ==
Um Innerhalb eines Moduls eine Log-Meldung in die FHEM-Logdatei zu schreiben, wird die Funktion [[DevelopmentModuleAPI#Log3|Log3()]] aufgerufen.
<syntaxhighlight lang="perl">
Log3 $name, 3, "X ($name) - Problem erkannt ...";
</syntaxhighlight>
Eine genaue Beschreibung zu der Funktion inkl. Aufrufparameter findet man [[DevelopmentModuleAPI#Log3|hier]]. Es ist generell ratsam in der Logmeldung sowohl den Namen des eigenen Moduls zu schreiben, sowie den Namen des Geräts, welche diese Logmeldung produziert, da die Meldung, so wie sie ist, direkt in das Logfile wandert und es für User ohne diese Informationen schwierig ist, die Meldungen korrekt zuzuordnen.

Die Funktion Log3() verwendet den Namen der Geräteinstanz um das <code>verbose</code>-Attribut zu prüfen. In der Regel wird bei Modulfunktionen jedoch immer nur der Gerätehash <code>$hash</code> übergeben. Um den Namen der Definition zu ermitteln ist es daher notwendig sich diesen aus dem Hash extrahieren:

<syntaxhighlight lang="perl">
my $name = $hash->{NAME};
</syntaxhighlight>

Um für eine einzelne Geräteinstanz das Verbose-Level zu erhöhen, ohne gleich für das gesamte FHEM den globalen Verbose-Level zu erhöhen und damit alle Meldungen zu erzeugen, kann man den Befehl
<code>attr <NAME> verbose</code> verwenden. Beispielsweise <code>attr Lichtschalter_Wohnzimmer verbose 5</code>

Logmeldungen sollten je nach Art und Wichtigkeit für den Nutzer in unterschiedlichen Loglevels erzeugt werden. Es gibt insgesamt 5 Stufen in denen geloggt werden kann. Standardmäßig steht der systemweite Loglevel (<code>global</code>-Attribut <code>verbose</code>) auf der Stufe 3. Die Bedeutung der jeweiligen Stufen ist in der {{Link2CmdRef|Lang=de|Anker=verbose}} beschrieben.

Während der Entwicklung eines Moduls kann man für eigene Debug-Zwecke auch die Funktion [[DevelopmentModuleAPI#Debug|Debug()]] verwenden um schnell und einfach Debug-Ausgaben in das Log zu schreiben. Diese sollten in der endgültigen Fassung jedoch nicht mehr vorhanden sein. Sie dienen ausschließlich zum Debugging während der Entwicklung.

Eine genaue Beschreibung der Log-Funktion gibt es [[DevelopmentModuleAPI#Logging|hier im Wiki]].

== Zweistufiges Modell für Module ==
[[Datei:Zweistufiges Modulkonzept.jpg|mini|rechts|Schematische Darstellung am Beispiel CUL]]
Es gibt viele Geräte, welche die Kommunikation mit weiteren Geräten mit tlw. unterschiedlichen Protokollen ermöglichen. Das typischste Beispiel bietet hier der [[CUL]], welcher via Funk mit verschiedenen Protokollen weitere Geräte ansprechen kann (z.B. Aktoren, Sensoren, ...). Hier bildet ein Gerät eine Brücke durch die weitere Geräte in FHEM zugänglich gemacht werden können. Dabei werden über einen Kommunikationsweg (z.B. serielle Schnittstelle, TCP, ...) beliebig viele Geräte gesteuert. Typische Beispiele dazu sind:

* [[CUL]]: stellt Geräte mit verschiedenen Kommunikationsprotokollen via Funk bereit (u.a. [[FS20]], [[HomeMatic]], [[Funk-Heizkörperregler_Kurz-Bedienungsanleitung_FHT|FHT]], [[MAX]], ...)
* [[HMLAN]]: stellt HomeMatic Geräte via Funk bereit
* [[MAX#MAXLAN|MAXLAN]]: stellt [[MAX|MAX!]] Geräte via Funk bereit
* [[PanStamp#panStick.2FShield|panStamp]]: stellt weitere panStamp Geräte via Funk bereit

Dabei wird die Kommunikation in 2 Stufen unterteilt:
* physisches Modul - z.B. 00_CUL.pm - zuständig für die physikalische Kommunikation mit der Hardware. Empfangene Daten müssen einem logischen Modul zugeordnet werden.
* logische Modul(e) - z.B. 10_FS20.pm - interpretiert protokollspezifische Nachrichten. Sendet protokollspezifische Daten über das physische Modul an die Hardware.

physisches Modul

Das physische Modul öffnet die Datenverbindung zum Gerät (z.B. CUL) und verarbeitet sämtliche Daten. Es kümmert sich um den Erhalt der Verbindung (bsp. durch Keep-Alives) und konfiguriert das Gerät so, dass eine Kommunikation mit allen weiteren Geräten möglich ist (bsp. Frequenz, Modulation, Kanal, etc.).

Empfangene Nutzdaten werden als Zeichenkette über die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] an logische Module weitergegeben.

Das Modul stellt eine [[#Die_Match-Liste|Match-Liste]] bereit, anhand FHEM die Nachricht einem Modul zuordnen kann, sofern dieses noch nicht geladen sein sollte. Die Match-Liste enthält eine Liste von regulären Ausdrücken und ordnet diese einem Modul zu. Wenn eine Nachricht auf einen solchen regulären Ausdruck passt und das Modul noch nicht geladen ist, lädt FHEM dieses automatisch nach, zwecks Verarbeitung der Nachricht.

Anhand einer bereitgestellten [[#Die_Client-Liste|Client-Liste]] (Auflistung von logischen Modulen) kann FHEM feststellen, welche logischen Module mit dem physischen Modul kommunizieren können. Nur die hier aufgelisteten, logischen Module werden beim Aufruf von [[DevelopmentModuleAPI#Dispatch|Dispatch()]] angesprochen.

Das Modul stellt eine [[#X_Write|Write]]-Funktion zur Verfügung, über die logische Module Daten in beliebiger Form an die Hardware übertragen können.

logisches Modul

Das logische Modul interpretiert die via Dispatch() übergebene Nachricht (Zeichenkette) durch eine bereitgestellte [[#X_Parse|Parse]]-Funktion und erzeugt entsprechende Readings/Events. Es stellt über <code>set</code>-/<code>get</code>-Kommandos Steuerungsmöglichkeiten dem Nutzer zur Verfügung.

Es stellt FHEM einen [[#Der_Match-Ausdruck|Match-Ausdruck]] (regulärer Ausdruck) zur Verfügung anhand [[DevelopmentModuleAPI#Dispatch|Dispatch()]] ermitteln kann, ob die Nachricht durch das logische Modul verarbeitet werden kann. Nur Nachrichten, welche auf diesen Ausdruck passen, werden an das logische Modul weitergegeben (Aufruf [[#X_Parse|Parse]]-Funktion).

=== Die Client-Liste ===

Die Client-Liste ist eine Auflistung von Modulnamen (genauer: regulären Ausdrücken die auf Modulnamen passen) die in einem physischen Modul gesetzt ist. Damit wird definiert, mit welchen logischen Modulen das physikalische Modul kommunizieren kann.

Eine Client-Liste ist eine Zeichenkette, welche aus allen logischen Modulnamen besteht. Die einzelnen Namen werden durch einen Doppelpunkt getrennt. Anstatt kompletter Modulnamen können auch reguläre Ausdrücke verwendet werden, die auf mehrere Modulnamen passen (z.B. <code>CUL_.*</code> um die logischen Module CUL_HM, CUL_MAX, etc. zu verwenden).

Bsp.: Die Client-Liste von dem Modul CUL lautet daher wie folgt:
{|
!
FS20:FHT.*:KS300:USF1000:BS:HMS:CUL_EM:CUL_WS:CUL_FHTTK:CUL_HOERMANN:ESA2000:CUL_IR:CUL_TX:Revolt:IT:UNIRoll:SOMFY:STACKABLE_CC:CUL_RFR:CUL_TCM97001:CUL_REDIRECT
|}
Alle hier aufgelisteten Module können über das Modul CUL Daten empfangen bzw. senden.

Die Client-Liste hat generell folgende Funktion:
* Die Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur Module, welche in der Client-Liste enthalten sind, ob diese die Nachricht verarbeiten können (Prüfung via [[#Der Match-Ausdruck|Match-Ausdruck]])
* Die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] prüft anhand sämtlicher Client-Listen in FHEM, welches IO-Gerät für ein logisches Gerät nutzbar ist.

Üblicherweise wird die Client-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;
...
$hash->{Clients} = "FS20:KS300:FHT.*";
}
</syntaxhighlight>

Man kann die Client-Liste jedoch auch pro physikalisches Gerät setzen. Eine gesetzte Client-Liste in einem Gerät hat immer Vorrang vor der Liste im Modul-Hash. Eine gerätespezifische Client-Liste wird dann verwendet, wenn bspw. ein Gerät je nach Konfiguration nur bestimmte logische Module bedienen kann. Bspw. kann ein CUL je nach RF-Einstellungen FS20, uvm. oder nur HomeMatic bedienen. In einem solchen Fall wird die Client-Liste im Geräte-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ( $hash, $def ) = @_;
...
$hash->{Clients} = "CUL_HM";
}
</syntaxhighlight>

In vielen Modulen, welche nach dem zweistufigem Konzept arbeiten, beginnt und endet die Client-Liste mit einem Doppelpunkt. Dies ist ein historisches Überbleibsel, da der Prüfmechanismus die Client-Liste früher auf das Vorhandensein von <code>''':'''<Modulname>''':'''</code> prüfte. Dies ist nun nicht mehr notwendig. Die einzelnen Modulnamen müssen lediglich durch einen Doppelpunkt getrennt werden.

=== Die Match-Liste ===
{{Randnotiz|RNTyp=Info|RNText='''ACHTUNG''':
Sämtliche regulären Ausdrücke in der Match-Liste werden "case insensitive" überprüft. Das bedeutet, dass Groß-/Kleinschreibung nicht berücksichtigt wird.

Um dennoch in einem regulären Ausdruck auf Groß-/Kleinschreibung zu prüfen, kann man dieses mit dem Modifizierer <code>(?-i)</code> wieder aktivieren:

<syntaxhighlight lang="perl">
my %matchListFHEMduino = (
....
"5:FHEMduino_PT2262" => "^(?-i)IR.*\$",
....
"13:IT" => "^(?-i)i......\$",
);
</syntaxhighlight>

Siehe dazu Forumsbeitrag: {{Link2Forum|Topic=33422}}
}}
Die Match-Liste ordnet eine Nachrichtensyntax (regulärer Ausdruck) einem Modulnamen zu und wird in einem physikalischen Modul gesetzt. Sollte eine Nachricht vom physikalischen Gerät empfangen werden, die durch kein geladenes Modul verarbeitet werden kann ([[DevelopmentModuleAPI#Dispatch|Dispatch()]] prüft nur alle bisher geladenen Module aus der [[#Die Client-Liste|Client-Liste]]), so wird über die Match-Liste geprüft, welches Modul diese Nachricht verarbeiten kann. Dieses Modul wird anschließend geladen und die Nachricht durch dieses direkt durch Aufruf der [[#X_Parse|Parse]]-Funktion verarbeitet. In dieser Liste findet mittels regulärem Ausdruck eine Zuordnung der Nachrichtenstruktur zum verarbeitenden logischen Modul statt.

Diese Liste wird ausschließlich in der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion verwendet. Sollte keine passendes Modul, welches bereits geladen ist, zur Verarbeitung einer Nachricht gefunden werden, so wird mithilfe der Match-Liste aufgrund der vorliegenden Nachricht das entsprechende Modul ermittelt. Dieses Modul wird dann direkt geladen und die Nachricht wird via [[#X_Parse|Parse]]-Funktion verarbeitet.

Die Match-Liste ist eine Zuordnung von einem Sortierpräfix + Modulname zu einem regulären Ausdruck:

<syntaxhighlight lang="perl">
{
"1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).."
}
</syntaxhighlight>

Das Sortierpräfix (<code>1:FS20</code>) dient als Sortierhilfe um so die Reihenfolge der Prüfung festzulegen. Bei der Prüfung wird die Match-Liste mittels sort() nach dem Schlüssel (Sortierpräfix + Modulname) sortiert und die regulären Ausdrücke werden dann nacheinander getestet. Daher sollten die präzisesten Ausdrücke immer zuerst getestet werden, sofern es weniger präzise Ausdrücke in der Match-Liste gibt. Dabei ist zu beachten, dass der Sortierpräfix nicht nach numerischen Regeln sortiert wird, sondern zeichenbasierend.

Üblicherweise wird die Match-Liste in der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{MatchList} = { "1:FS20" => "^81..(04|0c)..0101a001",
"2:KS300" => "^810d04..4027a001",
"3:FHT" => "^81..(04|09|0d)..(0909a001|83098301|c409c401).." };
}
</syntaxhighlight>

Man kann die Match-Liste, ähnlich wie bei der Client-Liste, auch pro physikalisches Gerät setzen. Dabei hat auch hier die Match-Liste eines Gerätes immer Vorrang vor der Match-Liste aus dem Modul-Hash:

<syntaxhighlight lang="perl">
sub X_Define($$)
{
my ($hash, $def) = @_;

...

$hash->{MatchList} = { "1:CUL_HM" => "^A...................." };
}
</syntaxhighlight>

=== Der Match-Ausdruck ===

Ein Match-Ausdruck wird in einem logischen Modul gesetzt und dient der Prüfung, ob eine Nachricht durch das eigene Modul via [[#X_Parse|Parse]]-Funktion verarbeitet werden kann. Es handelt sich hierbei um einen einzelnen regulären Ausdruck, den FHEM innerhalb der [[DevelopmentModuleAPI#Dispatch|Dispatch()]]-Funktion prüft. Nur wenn eine Nachricht via Dispatch() auf diesen Audruck matcht, wird die Parse-Funktion des eigenen Moduls aufgerufen um die Nachricht zu verarbeiten.

Der Hintergrund, warum man den Aufruf mit einem solchen Ausdruck vorher abprüft, liegt in der Möglichkeit, dass ein physikalisches Modul mehrere unterschiedliche logische Module ansprechen kann. So kann FHEM jedes geladene Modul durch diesen Match-Ausdruck prüfen, ob es diese Nachricht verarbeiten kann. Erst, wenn alle geladenen Module, aufgrund einer Prüfung des Ausdrucks, die Nachricht nicht verarbeiten können, wird via [[#Die_Match-Liste|Match-Liste]] ermittelt, welches Modul geladen werden muss um die Nachricht zu verarbeiten.

Der Match-Ausdruck wird in der [[#X_Initialize|Initialize]]-Funktion zur Verfügung gestellt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

# Dieses Modul verarbeitet FS20 Nachrichten
$hash->{Match} = "^81..(04|0c)..0101a001";
}
</syntaxhighlight>
=== Die vollständige Implementierung ===

Hier nun eine Zusammenfassung beim zweistufigen Modulkonzept in der jeweiligen Stufe implementiert werden muss, damit die Kommunikation funktioniert.

==== physisches Modul ====

Das physische Modul, welches als Kommunikationsbrücke zwischen der Hardware und logischen Modulen fungieren wird, sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Zum öffnen der Datenverbindung zur Hardware (IP-Adresse/serielle Schnittstelle/...).
* [[#X_Read|Read]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Read|Ready]]-Funktion - Zum Wiederaufbau der Verbindung bei Verbindungsabbruch, bzw. Prüfung auf lesbare Daten bei serieller Schnittstelle unter Windows.
* [[#X_Write|Write]]-Funktion - Zum Senden von Daten, welche logische Module via [[DevelopmentModuleAPI#IOWrite|IOWrite()]] an die Hardware übertragen möchten.
* [[#X_Undef|Undef]]-Funktion - Schließen der Verbindung zur Hardware beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.
* [[#X_Shutdown|Shutdown]]-Funktion - Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.
* [[#X_DelayedShutdown | DelayedShutdown]]-Funktion - Verzögertes beenden zum Schließen der Verbindung zur Hardware beim Stopp von FHEM via <code>shutdown</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Die_Client-Liste|Client-Liste]] - Auflistung aller logischen Module, die über dieses Modul kommunizieren können
* [[#Die_Match-Liste|Match-Liste]] - Zuordnung von Nachrichtensyntax zu Modul zwecks Autoload-Funktionalität.

==== logisches Modul ====

Das logische Modul, bildet ein einzelnes Gerät ab, über das mit einem physikalisches Modul kommuniziert werden kann. Es sollte mindestens folgende Funktionen implementieren:

* [[#X_Initialize|Initialize]]-Funktion - Zum Registrieren des Moduls in FHEM.
* [[#X_Define|Define]]-Funktion - Speichern des Definition Pointers (siehe [[#X_Parse|Parse-Funktion]])
* [[#X_Parse|Parse]]-Funktion - Zum Lesen von Daten, welche die Hardware übermittelt.
* [[#X_Undef|Undef]]-Funktion - Löschen des Definition Pointers beim Löschen via <code>delete</code> bzw. <code>rereadcfg</code>.

Desweiteren müssen in der [[#X_Initialize|Initialize]]-Funktion folgende Daten bereitgestellt werden:

* [[#Der_Match-Ausdruck|Match-Ausdruck]] - Prüfausdruck, ob eine Nachricht durch dieses Modul verarbeitet werden kann.

=== Kommunikation von der Hardware bis zu den logischen Modulen ===

Die Gerätedefinition des physischen Moduls öffnet eine Verbindung zur Hardware (z.B. via [[DevIo]]). Die [[#X_Read|Read]]-Funktion wird bei anstehenden Daten aus der Hauptschleife von fhem.pl aufgerufen.

Die Read-Funktion stellt dabei sicher, dass die Daten
* komplett (in der Regel über einen internen Puffer in <code>$hash</code>) und
* korrekt (z.B. via Prüfung mittels regulärem Ausdruck)
sind und ruft die globale Funktion [[DevelopmentModuleAPI#Dispatch|Dispatch()]] mit einer kompletten Nachricht auf.

Die Funktion Dispatch() prüft alle geladenen Module aus der [[#Die_Client-Liste|Client-Liste]] des physikalischen Moduls nach möglichen logischen Modulen zur Verarbeitung. Alle zum Zeitpunkt geladenen Module, die in der Client-Liste aufgeführt sind, werden über den [[#Der_Match-Ausdruck|Match-Ausdruck]] geprüft, ob sie mit der Nachricht etwas anfangen können. Sollte bei einem logischen Modul der Match-Ausdruck passen, so wird die entsprechende [[#X_Parse|Parse]]-Funktion des logischen Moduls aufgerufen. Sofern keine passendes Modul gefunden wurde, um die Nachricht zu verarbeiten, wird in der [[#Die_Match-Liste|Match-Liste]] im Geräte- bzw. Modul-Hash der physischen Gerätedefinition nach dem passenden Modul gesucht. Sollte es darin ein Modul geben, was diese Art von Nachricht verarbeiten kann, so wird versucht dieses Modul zu laden um nun die Nachricht via Parse-Funktion zu verarbeiten. Es erfolgt in diesem Fall keine Vorprüfung durch den Match-Ausdruck.

Durch Dispatch() wird nun die [[#X_Parse|Parse]]-Funktion des gefundenen logischen Moduls aufgerufen. Diese
* interpretiert die übergebene Nachricht,
* versucht eine existierende Gerätedefinition in FHEM zu finden (z.B. mittels Definition Pointer), für welche die Nachricht addressiert ist,
* setzt alle [[#Readings|Readings]] für die gefundene Gerätedefinition via [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen,
* gibt den Namen der logischen Definition zurück, welche die Nachricht verarbeitet hat.

Sollte keine passende Gerätedefinition für die entsprechende Nachricht existieren (Adresse/ID/Kanal/...), wird der Gerätename "UNDEFINED" inkl. einem passenden <code>define</code>-Statement zurückgegeben, um die Definition durch [[autocreate]] erzeugen zu lassen.

Es findet während der Verarbeitung einer Nachricht durch Dispatch()/Parse-Funktion keine sofortige Eventverarbeitung (via [[DevelopmentModuleAPI#Dispatch|DoTrigger()]]) statt, wenn die [[DevelopmentModuleAPI#Readings_.2F_Events|readings*update]]()-Funktionen verwendet werden.
(Im Gegensatz zum direkten Aufrufen der readings*update Funktionen ohne vorhergehendes Dispatch() )

Die Funktion Dispatch() triggert das Event-Handling für das von der Parse-Funktion zurückgegebene logische Device selbstständig nach Abschluss der Parse-Funktion.

Optional führt die Funktion Dispatch() eine Überprüfung auf Nachrichtenduplikate beim Einsatz von mehreren IO-Geräten durch. Dazu wird eine implementierte [[#X_Fingerprint|Fingerprint]]-Funktion im physischen oder logischen Modul benötigt. Sollte der Fingerprint einer Nachricht innerhalb einer bestimmten Zeit (globales Attribut <code>dupTimeout</code>, standardmäßig 500ms) bereits empfangen worden sein, so wird die Nachricht verworfen. Dies ist insbesondere bei funkbasierter Hardware notwendig, wenn mehrere Empfänger die selbe Nachricht empfangen.

=== Kommunikation von den logischen Modulen bis zur Hardware ===

Um von einem logischen Modul eine Nachricht an die Hardware senden zu können, muss zunächst im logischen Gerät ein passenden IO-Gerät ausgewählt sein. Dazu muss die Funktion [[DevelopmentModuleAPI#AssignIoPort|AssignIoPort()]] ein entsprechendes IO-Gerät auswählen und in <code>$hash->{IODev}</code> setzen. Dieser Aufruf wird üblicherweise in der [[#X_Define|Define]]-Funktion des logischen Moduls ausgeführt. Erst, wenn ein IO-Gerät ausgewählt wurde, können Daten über das physikalische Gerät an die Hardware übermittelt werden.

Zum Senden von Daten ruft das logische Modul die Funktion [[DevelopmentModuleAPI#IOWrite|IOWrite()]] samt Daten auf. Diese ruft für das entsprechende IO-Gerät die [[#X_Write|Write]]-Funktion auf und übergibt die Daten zum Schreiben an das physikalische Modul. Die Write-Funktion kümmert sich nun um die Übertragung der Daten an die Hardware.

Keine direkten Zugriffe zwischen dem logischen und dem physischen Gerät gibt (d.h. keine direkten Aufrufe von Funktionen, kein direktes Überprüfen von <code>$hash</code>-Inhalten, ...), so können die Module hintereinander geschaltet werden (z.B. für Routerfunktionen wie bei der [[RFR_CUL|RFR]]-Funktionalität) oder mittels [[FHEM2FHEM]] im RAW-Modus zwei FHEM-Installationen verbunden werden und die logischen Geräte können dennoch kommunizieren.

=== Automatisches Anlegen von logischen Gerätedefinitionen (autocreate) ===

Das logische Modul kann im Rahmen der [[#X_Parse|Parse]]-Funktion eine neue Gerätedefinition anlegen, sofern eine passende Definition nicht existieren sollte. Die Parse-Funktion gibt generell den Namen der logischen Gerätedefinition zurück, für welche die Nachricht verarbeitet wurde. Sollte keine passende Definition gefunden werden, so muss die Parse-Funktion folgenden Rückgabewert liefern (zusammenhängende Zeichenkette):

UNDEFINED ''<Namensvorschlag>'' ''<Modulname>'' ''<Define-Parameter...>''

Sollte also bspw. im Rahmen der Parse-Funktion zu Modul X eine Nachricht nicht einer existierenden Gerätedefinition zugeordnet werden können, so muss ein Namensvorschlag erstellt werden der eine eindeutige Komponente wie bspw. eine Adresse/ID/Kanal-Nr enthält. In der Regel wird hier immer der Modulname zusammen mit der eindeutigen Komponente, durch einen Unterstrich getrennt, verwendet (Bsp: <code>X_4834</code>). Der Modulname ist in der Regel immer der, des eigenen Moduls. In besonderen Fällen kann man hier auch einen abweichenden Modulnamen angeben. Dies wird bspw. bei den [[PanStamp#FHEM-Module.2FDevice_Definition_Files|SWAP-Modulen]] eingesetzt. Als Define-Parameter müssen alle notwendigen Parameter angegeben werden, die beim Aufruf des <code>define</code>-Befehls notwendig sind, damit eine neu angelegte Gerätedefinition Nachrichten zu dieser eindeutigen Adresse Daten verarbeitet. Dazu muss mind. die eindeutige Adresse mitgegeben werden.

Beispiel für FS20:

UNDEFINED FS20_0ae42f8 FS20 0ae42 f8

Sobald [[DevelopmentModuleAPI#Dispatch|Dispatch()]] einen solchen Rückgabewert von einer [[#X_Parse|Parse]]-Funktion erhält, wird diese Zeichenkette so wie sie ist via [[DevelopmentModuleAPI#DoTrigger|DoTrigger()]] als Event für die Definition <code>global</code> getriggert.

Sofern der Nutzer das Modul [[autocreate]] verwendet (definiert hat), kümmert sich dieses nun um das Anlegen einer entsprechenden Gerätedefinition. Es lauscht dabei auf generierte Events der Definition <code>global</code> via [[#X_Notify|Notify]]-Funktion. Der Nutzer kann dabei das Verhalten von autocreate durch entsprechende Parameter beeinflussen.

Das Modul, für welches autocreate eine neue Definition anlegen möchte, kann das Verhalten durch entsprechende Parameter im Modul-Hash beeinflussen. Dabei gilt, dass gesetzte Attribute durch den Nutzer generell Vorrang haben. Die entsprechenden Parameter werden dabei im Rahmen der [[#X_Initialize|Initialize]]-Funktion im Modul-Hash gesetzt:

<syntaxhighlight lang="perl">
sub X_Initialize($)
{
my ($hash) = @_;

...

$hash->{AutoCreate} = {"X_.*" => { ATTR => "event-on-change-reading:.* event-min-interval:.*:300",
FILTER => "%NAME",
GPLOT => "temp4hum4:Temp/Hum,",
autocreateThreshold => "2:140"
}
};

}
</syntaxhighlight>

Hierbei wird unterhalb von <code>$hash->{AutoCreate}</code> eine Liste angelegt, wo einem regulären Ausdruck für einen anzulegenden Definitionsnamen entsprechende Optionen zugeordnet werden. Sobald durch autocreate eine Gerätedefintion angelegt wird, auf den ein hier gelisteter Ausdruck matcht, so werden die zugeordneten Optionen berücksichtigt.

Hier eine Auflistung aller möglichen Optionen und ihrer Bedeutung:

{| class="wikitable"
|-
! Optionsname !! Beispiel !! Bedeutung
|-
| style="vertical-align:top; white-space: nowrap;" | <code>ATTR</code>|| style="vertical-align:top; white-space: nowrap;" | <code>"event-on-change-reading:.* event-min-interval:.*:300"</code> || Eine Auflistung von Attributen, die nach dem Anlegen einer Definition zusätzlich gesetzt werden. Es handelt sich hierbei um eine Leerzeichen-separierte Liste von Doppelpunkt-getrennten Tupels mit Attributname und -wert.

Für das dargestellte Beispiel bedeutet dies, dass nach dem Anlegen der Definition folgende FHEM-Befehle zusätzlich ausgeführt werden:

attr ''<Name>'' event-on-change-reading .*
attr ''<Name>'' event-min-interval .*:300

|-
| style="vertical-align:top; white-space: nowrap;" | <code>FILTER</code> || style="vertical-align:top; white-space: nowrap;" | <code>"%NAME"</code>|| Sofern in der autocreate-Definiton das Attribut <code>filelog</code> entsprechend durch den Nutzer gesetzt ist, wird eine zugehörige FileLog-Definition angelegt. Diese Option setzt den dabei benutzten Filter-Regexp, der beim Anlegen der FileLog-Definition gesetzt wird.

Dabei werden folgende Platzhalter durch die entsprechenden Werte der neu angelegten Gerätedefinition ersetzt:

* <code>%NAME</code> - wird ersetzt durch den Definitionsnamen
* <code>%TYPE</code> - wird ersetzt durch den Modulnamen
|-
| style="vertical-align:top; white-space: nowrap;" | <code>GPLOT</code> || style="vertical-align:top; white-space: nowrap;" | <code>"temp4hum4:Temp/Hum,"</code> || Sofern eine FileLog-Definition angelegt wurde, kann man weiterführend dazu eine passende SVG-Definition erzeugen um Daten aus dem erzeugten FileLog zu visualisieren. Ein typischer Fall sind hierbei Temperatursensoren, wo es sinnvoll sein kann, einen passenden SVG-Plot mit Temperatur/Luftfeuchtigkeit direkt anzulegen.

Es handelt sich hierbei um eine kommaseparierte Auflistung von gplot-Dateinamen und optionalen Label-Texten durch einen Doppelpunkt getrennt. Im genannten Beispiel entspricht <code>temp4hum4</code> der zu verwendenden GnuPlot-Datei und <code>Temp/Hum</code> dem zu verwendenden Label ([[SVG]] Attribut <code>label</code>). Das Label wird auch durch FileLog verwendet als Link-Text zum entsprechenden SVG Plot. Alternativ kann auch nur die entsprechende GnuPlot-Datei anegeben werden ohne Label. Für jede angegebene GnuPlot-Datei wird anschließend eine entsprechende SVG-Definition erzeugt mit der vorher erzeugten FileLog-Definition als Datenquelle.

Der gesamte Inhalt der <code>GPLOT</code>-Option wird beim Anlegen einer FileLog-Definition dem Attribut <code>logtype</code> als Wert plus dem Text <code>text</code> zugewiesen. Daher muss der Inhalt der Option <code>GPLOT</code> immer mit einem Komma enden.

|-
| style="vertical-align:top; white-space: nowrap;" | <code>autocreateThreshold</code> || style="vertical-align:top; white-space: nowrap;" | <code>"2:10"</code> || Definiert, wie viele Aufrufe (im Bsp: <code>2</code>) von autocreate innerhalb welcher Zeit (im Bsp: <code>10</code> Sek.) stattfinden müssen, bevor die Gerätedefinition tatsächlich durch autocreate angelegt wird. Dadurch kann das ungewollte Anlegen von Geräten verhindert werden die tatsächlich nicht in Echt existieren. Aufgrund von Funkstörungen kann es durchaus zum ungewollten Anlegen einer Definition kommen. Diese Funktion lässt eine Definition erst zu wenn innerhalb einer vorgegeben Zeit eine Mindestzahl an Nachrichten eintrifft.

Die erste Zahl stellt dabei die Mindestanzahl an Nachrichten dar. Die Zweite Zahl stellt die Zeit in Sekunden dar, in der die Mindestanzahl an Nachrichten erreicht werden muss um eine entsprechende Gerätedefinition anzulegen.

Sofern diese Option nicht gesetzt ist, wird standardmäßig <code>2:60</code> verwendet.

Diese Option kann durch den Anwender über das Attribut <code>autocreateThreshold</code> übersteuert werden.
|-
| style="vertical-align:top; white-space: nowrap;" | <code>noAutocreatedFilelog</code>|| style="vertical-align:top; white-space: nowrap;" | <code>1</code>|| Flag. Sofern gesetzt, wird keine FileLog- und ggf. SVG-Definition erzeugt. Selbst wenn der Nutzer durch entsprechende Attribute das Anlegen wünscht. Diese Option ist sinnvoll für Module bzw. Geräte die keine Readings erzeugen.
|}

== Ergänzende Hinweise ==
Die Wahl der vorangestellten Nummer für den Dateinamen eines neuen Moduls hat keine Bedeutung mehr, es sei denn die Nummer ist 99. Module, die mit 99_ beginnen, werden von FHEM automatisch geladen. Module mit einer anderen Nummer nur wenn ein <code>define</code>-Befehl dafür sorgt, dass das Modul geladen wird.

Wenn ein Modul Initialisierungsdaten benötigt, sollten diese im Modul selbst enthalten sein. Eine zusätzliche Datei oder sogar ein Unterverzeichnis mit mehreren Dateien ist bei FHEM nicht üblich und sollte bei Modulen, die mit FHEM ausgeliefert werden nur in Rücksprache mit Rudolf König angelegt werden, da sie sonst bei einem Update nicht verteilt werden.

== Weitere Informationen ==
Wenn man weitere Details wissen möchte, ist ein erster sinnvoller Schritt ein Blick in die Datei fhem.pl. Dort sieht man im Perl-Code wie die Module aufgerufen werden, was vorher passiert und was danach. Am Anfang der Datei (ca. ab Zeile 130) findet man beispielsweise eine Liste der globalen Variablen, die den Modulen zur Verfügung stehen sowie Details zu den wichtigen Hashes %modules und %defs. Wer mit Perl noch nicht so gut klar kommt, dem hilft eventuell ein Blick auf die Perldoc Website[http://perldoc.perl.org/] oder in das Perl-Buch seiner Wahl. Auch die FHEM {{Link2CmdRef}} sollte nicht unterschätzt werden. Es stehen oft mehr interessante Details auch für Modulentwickler darin als man zunächst vermuten könnte.

== "Hello World" Beispiel ==

98_Hello.pm

<syntaxhighlight lang="perl">
package main;
use strict;
use warnings;

my %Hello_gets = (
"whatyouwant" => "can't",
"whatyouneed" => "try sometimes",
"satisfaction" => "no"
);

sub Hello_Initialize($) {
my ($hash) = @_;

$hash->{DefFn} = 'Hello_Define';
$hash->{UndefFn} = 'Hello_Undef';
$hash->{SetFn} = 'Hello_Set';
$hash->{GetFn} = 'Hello_Get';
$hash->{AttrFn} = 'Hello_Attr';
$hash->{ReadFn} = 'Hello_Read';

$hash->{AttrList} =
"formal:yes,no "
. $readingFnAttributes;
}

sub Hello_Define($$) {
my ($hash, $def) = @_;
my @param = split('[ \t]+', $def);

if(int(@param) < 3) {
return "too few parameters: define <name> Hello <greet>";
}

my $hash->{name} = $param[0];
my $hash->{greet} = $param[2];

return undef;
}

sub Hello_Undef($$) {
my ($hash, $arg) = @_;
# nothing to do
return undef;
}

sub Hello_Get($@) {
my ($hash, @param) = @_;

return '"get Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
if(!$Hello_gets{$opt}) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}

if($attr{$name}{formal} eq 'yes') {
return $Hello_gets{$opt}.', sir';
}
return $Hello_gets{$opt};
}

sub Hello_Set($@) {
my ($hash, @param) = @_;

return '"set Hello" needs at least one argument' if (int(@param) < 2);

my $name = shift @param;
my $opt = shift @param;
my $value = join("", @param);

if(!defined($Hello_gets{$opt})) {
my @cList = keys %Hello_gets;
return "Unknown argument $opt, choose one of " . join(" ", @cList);
}
$hash->{STATE} = $Hello_gets{$opt} = $value;

return "$opt set to $value. Try to get it.";
}

sub Hello_Attr(@) {
my ($cmd,$name,$attr_name,$attr_value) = @_;
if($cmd eq "set") {
if($attr_name eq "formal") {
if($attr_value !~ /^yes|no$/) {
my $err = "Invalid argument $attr_value to $attr_name. Must be yes or no.";
Log 3, "Hello: ".$err;
return $err;
}
} else {
return "Unknown attr $attr_name";
}
}
return undef;
}

1;

=pod
=begin html

<a name="Hello"></a>
<h3>Hello</h3>
<ul>
Hello implements the classical "Hello World" as a starting point for module development.
You may want to copy 98_Hello.pm to start implementing a module of your very own. See
<a href="http://wiki.fhem.de/wiki/DevelopmentModuleIntro">DevelopmentModuleIntro</a> for an
in-depth instruction to your first module.
 
<a name="Hellodefine"></a>
Define
<ul>
<code>define <name> Hello <greet></code>
 
Example: <code>define HELLO Hello TurnUrRadioOn</code>
 
The "greet" parameter has no further meaning, it just demonstrates
how to set a so called "Internal" value. See <a href="http://fhem.de/commandref.html#define">commandref#define</a>
for more info about the define command.
</ul>
 

<a name="Helloset"></a>
Set 
<ul>
<code>set <name> <option> <value></code>
 
You can set any value to any of the following options. They're just there to
get them. See <a href="http://fhem.de/commandref.html#set">commandref#set</a>
for more info about the set command.
 
Options:
<ul>
<li>satisfaction 
Defaults to "no"</li>
<li>whatyouwant 
Defaults to "can't"</li>
<li>whatyouneed 
Defaults to "try sometimes"</li>
</ul>
</ul>
 

<a name="Helloget"></a>
Get 
<ul>
<code>get <name> <option></code>
 
You can get the value of any of the options described in
<a href="#Helloset">paragraph "Set" above</a>. See
<a href="http://fhem.de/commandref.html#get">commandref#get</a> for more info about
the get command.
</ul>
 

<a name="Helloattr"></a>
Attributes
<ul>
<code>attr <name> <attribute> <value></code>
 
See <a href="http://fhem.de/commandref.html#attr">commandref#attr</a> for more info about
the attr command.
 
Attributes:
<ul>
<li>formal no|yes 
When you set formal to "yes", all output of get will be in a
more formal language. Default is "no".
</li>
</ul>
</ul>
</ul>

=end html

=cut
</syntaxhighlight>

Der HTML-Code zwischen den Tags <code>=pod</code> und <code>=cut</code> dient zur Generierung der commandref.html. Der HTML-Inhalt wird automatisch beim Verteilen des Moduls im Rahmen des Update-Mechanismus aus jedem Modul extrahiert und daraus die Commandref in verschiedenen Sprachen erstellt. Eine detaillierte Beschreibung wie ein Commandref-Abschnitt in einem Modul definiert wird, siehe: [[Guidelines zur Dokumentation]]

[[Kategorie:Development]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-04-19T15:39:18Z

Xaneu: /* PIUSV+ und Raspberry Pi 4 */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung, Akku-Spannung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang="pl">
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== PIUSV+ und Raspberry Pi 4 ==
Obwohl die PIUSV+ nur 2 A liefern kann, ist der Betrieb mit einem Raspberry Pi 4 durchaus möglich, sofern auf dem Raspberry hauptsächlich der FHEM-Server und keine sonstige hochperformante Software installiert ist.
Bei einer FHEM-Beispielinstallation (Raspian Buster, FHEM 6.0) mit USB-SSD-Platte (32GB), 3x USB/232-Konverter, einem Homematic-Sender/Empfängermodul (HM-MOD-PRI-PCB) und Nutzung der 1-Wire-, I²C- und 2xGPIO-Schnittstellen am 40pol. Pfostenverbinder beträgt der 5V-Versorgungsstrom ca. 0,9A (entspricht 4,5W).

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-04-19T14:30:22Z

Xaneu: /* PIUSV+ und Raspberry Pi 4 */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung, Akku-Spannung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang="pl">
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== PIUSV+ und Raspberry Pi 4 ==
Obwohl die PIUSV+ nur 2 A liefern kann ist der Betrieb mit einem Raspberry Pi 4 durchaus möglich, sofern auf dem Raspberry hauptsächlich der FHEM-Server und keine sonstige hochperformante Software läuft. 
Bei einer FHEM-Beispielinstallation (Raspian Buster, FHEM 6.0) mit USB-SSD-Platte (32GB), 3x USB/232-Konverter, ein Homematic-Sender/Empfängermodul (HM-MOD-PRI-PCB) und ein paar Schnittstellen über den 40pol. Pfostenverbinder (1-Wire, I²C- und 2 GPIOs) beträgt der 5V-Versorgungsstrom ca. 0,9A (entspricht 4,5W).

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-04-19T14:23:07Z

Xaneu:

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung, Akku-Spannung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== PIUSV+ und Raspberry Pi 4 ==
Obwohl die PIUSV+ nur 2 A liefern kann ist der Betrieb mit einem Raspberry Pi 4 durchaus möglich, sofern auf dem Raspberry hauptsächlich der FHEM-Server und keine sonstige hochperformante-Software läuft. 
Eine FHEM-Beispielinstallation (Raspian Buster, FHEM 6.0) mit USB-SSD-Platte (32GB), 3x USB/232-Konverter, ein Homematic-Sender/Empfängermodul (HM-MOD-PRI-PCB) und ein paar Schnittstellen über den 40pol. Pfostenverbinder (1-Wire, I²C- und 2 GPIOs) beträg der 5V-Versorgungsstrom ca. 0,9A (entspricht 4,5W).

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

HMinfo

2020-04-15T20:26:38Z

Xaneu: /* Integritätsprüfungen */

{{Infobox Modul
|ModPurpose=Übersicht über alle HomeMatic Geräte
|ModType=h
|ModCmdRef=HMinfo
|ModForumArea=HomeMatic
|ModTechName=98_HMinfo.pm
|ModOwner=martinp876 ({{Link2FU|251|martinp876}} / [[Benutzer Diskussion:Martinp876|Wiki]])
}}

'''HMInfo''' ist ein Modul, das einen Überblick über alle definierten [[HomeMatic]] Geräte gibt. Es bietet Funktionen zur Übersicht, Kontrolle, Archivierung und, begrenzt, zur Programmierung der HomeMatic Komponenten. Somit soll es eine Hilfestellung bei Konfiguration und Fehlerbehandlung geben.

== Definition ==
HMInfo wird erstellt / angelegt mit dem Befehl
:<code>define hm HMinfo</code>

Danach können alle Funktionen aufgelistet werden mit
:<code>get hm help</code>

== Integritätsprüfungen ==
Zu berücksichtigen bei allen Funktionen von HMInfo ist die Tatsache, dass die Prüfung jeweils auf den innerhalb von FHEM vorliegenden Informationen passiert. Erste Korrekturmaßnahme ist daher immer von den betroffenen Devices die Informationen mit einem set <Device> getConfig zu aktualisieren. Dabei ist darüber hinaus zu berücksichtigen, dass entsprechend der konfigurierten Kommunikationsmethode (z.B. config) einige Devices erst nach einer gewissen Zeit oder nach Betätigen der Anlerntaste die Informationen als Antwort zurückliefern.

Befehle, um die Gültigkeit von verschiedenen HomeMatic Eigenschaften zu überprüfen:

=== peerCheck ===
Mit dem Befehl
:<code>get hm peerCheck</code>
wird der Zustand der Peerings überprüft, d.h., ob alle [[Peering (HomeMatic)|Peerings]] auch beidseitig sind. Mögliche Meldungen, die eine Überarbeitung und/oder Korrektur von Definitionen erforderlich machen können:
;peer not verified. Check that peer is set on both sides
:ausgegebener Wert (z.B.): actorChan p:switchChan
:erforderliche Korrekturmaßnahme: Erneutes setzen des Links und Sicherstellen, dass das Kommando das entsprechende Device auch erreicht hat (s.o., ggf. bei Bedarf die Anlerntaste betätigen).

=== regCheck ===
Mit dem Befehl
:<code>get hm regCheck</code>
wird überprüft, ob alle Register korrekt gelesen wurden. Mögliche Meldungen:
;missing register list
:ausgegebener Wert (z.B.): <code>dev01Ch01: RegL_01: </code>
:erforderliche Korrekturmaßnahme: <code>set dev01Ch01 getConfig</code>
:oder <code>device01Ch01: .RegL_03:sensor01Ch01,.RegL_03:sensor01Ch02</code>
:erforderliche Korrekturmaßnahme: Deutet darauf hin, dass nicht alle Informationen aus einem Device gelesen wurden. Ein set <Device> getConfig sollte alle Register auslesen. Sicherstellen, dass das Kommando zum Auslesen das entsprechende Device auch erreicht und eine Antwort geliefert hat (s.o., ggf. bei Bedarf die Anlerntaste betätigen).
;Register changes pending
:ausgegebener Wert (z.B.): <code>sensor01Ch01</code>
:erforderliche Korrekturmaßnahme: Ein set <Device> getConfig sollte alle Register auslesen. Sicherstellen, dass das Kommando das entsprechende Device auch erreicht und eine Antwort geliefert hat (s.o., ggf. bei Bedarf die Anlerntaste betätigen).

=== configCheck ===
Mit dem Befehl
:<code>get hm configCheck</code> werden die Befehle '''peerCheck''' und '''regCheck''' ausgeführt. Zusätzlich können noch Ergebnisse auftauchen wie
;PairedTo mismatch to IODev
:ausgegebener Wert (z.B.): <code>sensor01Ch01 paired:0x000000 IO attr: xxxxxx.</code>
:erforderliche Korrekturmaßnahme: IODevice in den hmPairForSec Modus versetzen, Pairing-Modus am Device aktivieren und dadurch das pairing wiederholen. Ein Anschließendes set <Device> getConfig kann nicht schaden. Sicherstellen, dass das Kommando zum Auslesen das entsprechende Device auch erreicht und eine Antwort geliefert hat (s.o., ggf. bei Bedarf die Anlerntaste betätigen).

== Anzeigen zur Übertragungssituation ==
===RSSI ===
;<code>get hm rssi [<filter>]</code>
:Erzeugt eine Tabelle aller RSSI Werte.
;<code>set hm clear [<filter>] rssi</code>
:setzt die RSSI Werte aller devices gemäß filter zurück. Eine neue Messung kann beginnen

===protoEvents ===
;<code>get hm protoEvents [<filter>][short|long] </code>
Siehe [[HMinfo Protokoll]]
:Es wird eine Tabelle mit allen wichtigen Ereignissen zur Datenübertragung erzeugt. Dies beinhaltet Wiederholungen sowie Übertragungsfehler.
<code>short</code> ist eine Fassung ohne Zeitstempel und lässt sich besser am Bildschirm darstellen.
Ausserdem kann man sehen, welche Abfragen noch in der Queue sind, z.B. durch <code>autoReadReg</code> erzeugt.
Die Zustände aller für HM zuständigen IOs sind beinhaltet.
Alles in allem ist hier ein kompletter Überblick zur Kommunikation zu sehen. Der Befehl
set hm clear [<filter>] Protocol
setzt die Protokoleinträge aller HomeMatic-Geräte gemäß Filter zurück. Das kann gut vor einer Konfigurationsaktion genutzt werden um zu kontrollieren, ob Fehler aufgetreten sind. 
Für tieferes Verständnis siehe [[HMinfo Protokoll]]

===msgStat===
;<code>set hm msgStat </code>
:Statistic der Übertragenen Messages insgesamt. Es gibt eine Tabelle über die letzten 24h und eine über die letzte Woche.

== Speichern von Konfigurationen==
HMInfo speichert Konfigurationen der Geräte in Files. Mit dem Attribut configDir kann man ein Verzeichnis festlegen, in das alles geschrieben wird.

=== saveConfig===
[[Peering (HomeMatic)|Peers]] und Register werden in eine Datei geschrieben. Die Daten kann man ggf. wieder in ein Gerät oder ein Austauschgerät schreiben. Die Speicherung erfolgt kumulativ, man kann alles in eine Datei schreiben.
:<code>set hm saveConfig [<filter>] [<file>] </code>

=== archConfig ===
Arbeitet prinzipiell wie saveConfig. Es werden jedoch nur vollständige Registersätze gespeichert, was einen höheren Level an Sicherheit der Dateninhalte gewährt.
:<code>set hm archConfig [-a] [<file>] </code>
Mit dem '''Attribut autoArchive''' kann man einstellen, dass automatisch nach erfolgreichem Lesen einer Device-Konfiguration diese archiviert wird.
Das Speichern erfolgt kumulativ. Ab einer Dateigröße von 1MB wird gepurged, also alles bis auf den neusten Eintrag jeder Entity gelöscht.

Um eine Konfiguration zu sichern, sollte eine Kopie des Archivs gemacht werden. Das Archiv wird bei Gelegenheit überschrieben.

Template erstellen:
:<code>set hm saveConfig -f ^meinDevice$ <myTemplateFile> </code>

=== loadConfig ===
;<code>set hm loadConfig [<filter>] [<filename>] </code>
:Liest die Registerwerte, die für eine Entity in einem File gespeichert sind, zurück in die Readings. Sollten die Register schon in FHEM vorhanden sein, wird '''nicht''' überschrieben.
Sinn macht dies beispielsweise für remotes, die nicht automatisch gelesen werden sollen. Man kann somit nach einem system-reboot die Register "rekonstruieren" und wieder darstellen.
Es liegt im ermessen des User, eine bekannt aktuelle Version der Register einzulesen.

=== purgeConfig===
;<code>set hm purgeConfig [<filename>] </code>
:Löscht alle älteren Datensätze in einem File.

== Konfigurationen bearbeiten ==
=== Templates ===
HMInfo erlaubt das Erstellen und Nutzen von Templates. Das sind Schablonen, die das Setzen von Registern abstrahieren und auf eine höhere Ebene heben. So kann man das Setzen der Konfiguration eines Aktors beispielsweise um mit einem Bewegungsmelder zusammen zu arbeiten in einem Kommando zusammenfassen.
Faktisch setzt das Template also eine Gruppe von Registern auf einmal.

====templateList ====
Die vorhandenen templates kann man mit templateList sehen.
get hm templateList

SwOnCond params:level cond Info:switch: execute only if condition [geLo|ltLo] level is below limit
SwToggle params: Info:Switch: toggle on trigger
autoOff params:time Info:staircase - auto off after <time>, extend time with each trigger
motionOnDim params:ontime brightness Info:Dimmer: on for time if MDIR-brightness below level
motionOnSw params:ontime brightness Info:Switch: on for time if MDIR-brightness below level
Die Liste der verfügbaren Tempaltes, deren Parameter falls nötig und eine kurze Info, was das Template bewirken soll

get hm templateList autoOff

autoOff params:time Info:staircase - auto off after <time>, extend time with each trigger
ActionType :jmpToTarget
OffTime :111600
OnTime :time
SwJtDlyOff :dlyOn
SwJtDlyOn :no
SwJtOff :dlyOn
SwJtOn :on
Ein templateList auf ein einzelnes Template zeigt im Detail, was das Template verändern wird.

====templateSet ====
Um ein Template auf einen Aktor anzuwenden,muss man den Bereich wählen, auf den er angewendet werden soll. Je nach template kann das die Gruppe der Register zu einem [[Peering (HomeMatic)|Peer]], zu short oder long eines Peer oder Register ohne peer sein.
set hm templateSet <entity> <templateName> <peer:[long|short]> [<param1> ...]
set hm templateSet Licht1 autoOff FB1_Btn2:short 10
set hm templateSet Licht1 SwOn FB1_Btn2:long
set hm templateSet Licht1 SwOff FB1_Btn2:short
set hm templateSet Licht1 SwOnOff FB1_Btn2:both
set hm templateSet LichtDev setHost 0
Licht1 soll, wenn ein kurzer Trigger von FB1_Btn2 kommt für 10 sec eingeschaltet werden, dann ausgehen (Treppenhausfunktion). Kommt aber ein langer Tastendruck wird das Licht dauerhaft eingeschaltet.
set hm templateSet Licht1 motionOnSw MD1:short 30 20
Der Switch Aktor Licht1 soll mit einem Bewegungsmelder betrieben werden. Der Bewegungsmelder sendet keine 'langen' Trigger sondern nur kurze. Im Beispiel wird Licht1 für 30 Sekunden eingeschaltet, wenn der Bewegungsmelder einen Trigger sendet UND es dunkler ist als "20" (Brightness level).

====templateDef ====
Neben den vorbereiteten Templates kann der User eigene definieren oder von anderen Usern sich Templates geben lassen. Die Definition von Templates ist für erfahrene User gedacht, im Gegensatz zur Nutzung eines Templates mit set - das ist für Anfänger gedacht. Man kann sein template manuell definieren oder ein bekanntes Device als Muster nutzen (fromMaster). Ein Template kann nur Gruppen von Registern setzen, nicht alle Register eines Device. Um die Gruppen anzusprechen muss man "peer" wie folgt setzen:
0 Register ohne peer
<peer>:both Register eines peers
<peer>:short Register eines peers nur Short
<peer>:long Register eines peers nur Long
setzen.
Man kann das template "dynamisch" gestalten, indem man einzelne Register beim templateSet übergibt.
Erst einmal statische Templates. Param ist hier "0"

set hm templateDef <templateName> <param1[:<param2>...]> <description> <reg1>:<val1> [<reg2>:<val2>] ...

set hm templateDef t1 0 "TP1" OnTime:10 OffTime:20 OnDly:0

set hm templateDef t1 fromMaster <entity> 0
set hm templateDef t2 fromMaster <entity> <peer>:both
set hm templateDef t3 fromMaster <entity> <peer>:short
set hm templateDef t4 fromMaster <entity> <peer>:long

set hm templateDef t4 fromMaster LichtWz remoteBtn1:long

Dynamische Templates haben eine Parameterliste (bis zu 9) <param1[:<param2>...]>. Diese werden als p0 bis p8 genutzt - der Name ist dabei egal, er dient dem User also Hilfe beim templateList

set hm templateDef myTemplate anzeit:auszeit "licht schaltet ständig an und aus" OnTime:p0 OffTime:p1 OnDly:0

set hm templateDef myAutoOff AnZeit "treppenhausschalter" ActionType:jmpToTarget OffTime:unused OnTime:p0 SwJtDlyOff:dlyOn SwJtDlyOn:no SwJtOff:dlyOn SwJtOn:on

Die "Anzeit" ist der erste Parameter, also p0. Der Wert, den man bei Set einträgt wird in OnTime geschrieben. OnTime:p0

Beim Definieren eines Templates wird die Registergültigkeit nicht geprüft. Das kommt beim Set.

Mit dem Parameter del kann ein (fehlerhaftes) Template (hier myTemplate) wieder gelöscht werden.

set hm templateDef myTemplate del

====templateChk ====
Template definitionen und zuweisungen (set) kann man mit
set hm archConfig
speichern und mit
set hm loadConfig
mach einem reboot laden. Welche templates einer entity zugewiesen sind kann man mit
attr <entity> expert 12
in den Readings sichtbar machen. Siehe auch templateUsg.

Man kann prüfen, ob ein Aktor/[[Peering (HomeMatic)|Peer]] gemäss einem Template programmiert ist. Sinnvoll ist eine komplette Prüfung aller zugewiesenen templates. Man kann aber auch filtern.
get hm templateChk
get hm templateChk [<filter>]
get hm templateChk [<filter>] <templateName> <peer:[long|short]> [<param1> ...]
get hm templateChk -f Rollo RolloHoch self01 5
Es wird geprüft für alle HM-Komponenten, die "Rollo" im Namen haben (siehe [[Homematic HMInfo#Filter|Filter]]) dem (hoffentlich vorhandenen) template "RolloHoch" verglichen. Geprüft wird nur der Peer "self01", aber für long UND short.
get hm templateChk -f Rollo RolloHoch self01:sort 5
das selbe, nur für short Einträge

====templateUsg ====
Gibt eine Liste der zugewiesenen templates zurück
get hm templateUsg
get hm templateUsg sortTemplate
get hm templateUsg sortPeer

====templateExe ====
Nach einem loadConfig oder einem templateChk können Fehler erkannt worden sein, die Register entspreche nicht dem Template. Mit diesem Kommando werden alle nicht korrekten Register in die Devices geschrieben. Sollte die Werte stimmen wird nichts gemacht.
set hm templateExe

Das Kommando kann also bedenkenlos eingesetzt werden, wenn die templates schon stimmen. Es wird nichts gesendet, keine Funklast erzeugt.

====templateDel ====
eine zuweisung des Templates kann gelöscht werden
set hm templateDel <entity> <template>

===Temperaturlisten===
HMInfo bietet verschiedene Methoden, Temperaturlisten für Thermostate (CC-TC, TC-IT oder RT) zu verwalten und zu nutzen. Siehe hierzu [[HomeMatic HMInfo TempList/Weekplan|Homematic Weekplan]]

=== Registersätze kopieren ===
HMInfo erlaubt das Kopieren von Register-Listen. Über Register wird ein HM-Gerät eingestellt und die Register sind in Listen gruppiert. Die Reaktion und das Verhalten eines Aktors auf einen Trigger eines Sensors wird in dem Registersatz zu diesem [[Peering (HomeMatic)|Peer]] komplett beschrieben.
Durch die Möglichkeit einen solchen Registersatz im Device zu kopieren kann man das Verhalten, das man für einen Knopf/Sensor festgelegt hat identisch in einen zweiten kopieren.
HMInfo geht davon aus, dass die vom Gerät gelesene Konfiguration vor dem Kommando aktuell und komplett ist.
set hm cpRegs Licht1:FB3_Btn2 Licht3:FB1_Btn4
set hm cpRegs Licht2:FB3_Btn2 Licht2:FB1_Btn4
set hm cpRegs Licht4:FB3_Btn2 Licht4:FB5_Btn2
Die obigen Beispiele bewirken der Reihe nach:
Duplizieren das Verhalten, das Fernbedienungsknopf 2 der Fernbedienung 3 bei Aktor Licht1 hervorruft auch nach Licht3 für Fernbedienungsknopf4 der Fernbedienung 1.
Duplizieren das Verhalten, das Fernbedienungsknopf 2 der Fernbedienung 3 bei Aktor Licht2 hervorruft auch nach Licht2 (selber Aktor) für Fernbedienungsknopf4 der Fernbedienung 1.

== Web Einträge und Readings ==
Readings und Internals von HMInfo bieten eine Zusammenfassung des Zustands aller HM Komponenten. Diese sind in Fehler '''ERR' , Warnungen '''W_''' und Information '''I_''' untergliedert. Die Prüfung und Erneuerung der Zähler und Werte wird mit:'''
:<code>set hm update </code>
erreicht. Mit dem Attribut autoUpdate kann man es automatisch regelmäßig starten.

=== Fehlermeldungen ===
Als Fehler erkannte Zustände werden in Variablen beginnend mit '''ERR''' dargestellt. Erfasste Fehler sind kritische RSSI Werte und Protokoll-/Übertragungsfehler. Ausserdem kann man im Attribut sumERROR eintragen, welche Readings zu einer Fehlermeldung führen sollen. Eingetragen werden:
Reading:<gutwert>. Wenn ein Reading mit einen anderen als dem "gutwert" gefunden wird, wird dies alarmiert.
Beispiel:
:<code>battery:ok </code>
hat eine HM Komponente ein Reading "battery" und dieses hat einen anderen Wert als "ok" wird dies alarmiert.
In den Readings von HMInfo würde im Feherfall
internal:
ERR_names <devicename1>,<devicename2>
Readings:
ERR_battery low:2

Der default aller Error-meldungen ist
battery:ok,sabotageError:off,powerError:ok,overload:off,overheat:off,reduced:off,motorError:no,error:none,uncertain:yes,smoke_detect:none,cover:closed

Diese Zusammenfassung der Fehlermeldungen könnte man nutzen, um über notify einen Alarm auszulösen oder eine E-Mail zu senden.

=== Warnungen===
Hierzu gehören Wiederholungen von Nachrichten (nicht aber Abbrüche, das sind Fehler). Es wird auch ausstehendes Lesen der Konfiguration, das durch autoReadReg getriggert wird, hier angezeigt.

=== Statusmeldungen ===
Analog zu den Fehlermeldungen kann man mit dem Attribut sumStatus gewisse Readings zählen lassen. Beipiel wäre
attr HM sumStatus motor
HMInfo zeigt in dem Reading I_sum_motor dann an, welcher Inhalt des Readings "motor" wie oft gefunden wurde. Es könnte so aussehen
stop:on:4;stop:1;
Vier Komponenten stehen auf motor: stop:on und eine steht auf motor: stop

Das Internal '''I_HM_IOdevices''' zeigt die von HM Komponenten genutzten IOs und deren State.

== Infos ==
get hm models [-f <regexp>]
get hm models
get hm models -f remote
get hm models -f HM_RC
Zeigt alle in FHEM unterstützten Modelle und deren wesentliche Parameter. Man kann mittels regexp die Liste filtern.

get hm param [<typefilter>] [-f <nameFilter>] parameter1 parameter2
get hm param -d IODev DEF model
get hm param -c -f Rollo peerList
man kann sich listen von Parametern anzeigen lassen

get hm register [<typefilter>] [-f <nameFilter>]
zeigt Register in tabellarischer Form.

get hm peerXref[<typefilter>] [-f <nameFilter>]
gibt an, wer mit wem [[Peering (HomeMatic)|gepeert]] ist

== Rücksetzen von Variablen und Zählern ==
set HM clear [<typeFilter>] [Protocol|readings|msgStat|register|rssi]
*register löscht alle Register-readings
*readings löscht '''alle''' readings
*Protocol löscht alle Protokol-einträge, pending Kommandos und Protokoll-fehler.
*rssi löscht alle ermittelten RSSI Werte
*msgStat setzt die Message Statistik zurück

== Filter ==
Kommandos in HMInfo wirken auf alle HM Komponenten. Man kann dies mit Hilfe der Filter einschränken. Zum einen gibt es '''modelsFilter''', womit man nur devices, nur channels, nur virtuelle Entities bearbeiten kann
set <name> <cmd> '''[-dcasevi]''' [params]
entities according to list will be processed"
d - device :include devices"
c - channels :include channels"
i - ignore :include devices marked as ignore"
v - virtual :supress fhem virtual"
p - physical :supress physical"
a - aktor :supress actor"
s - sensor :supress sensor"
e - empty :include results even if requested fields are empty"

Ein auf '''-d''' gefiltertes Kommando wird nur auf devices, nicht aber auf channels angewendet.

Dann gibt es noch den '''nameFilter''', mit dem mittels regexp auf den Namen der Entity gefiltert werden kann
-f Rollo # alle Entities mit Rollo im Namen
-f ^Rollo$ # nur Entity mit Namen "Rollo"
-f Rollo$ # nur Entity deren Name auf Rollo endet

Die Filter kann man kombinieren mit
-c -f Rollo # alle Kanäle mit Rollo im Namen

Beispiel:
Zeige mir die Parameter IODev und room der Devices mit Rollo im Namen
set hm param -d -f Rollo IODev room

== Attribute ==
* '''autoArchive ''' automatisch archivieren von vollständigen Konfigurationen.
* '''autoUpdate''' startet regelmäßig das Komamndo "update". Die Wiederholzeit wird eingestellt mit hh:mm. Sinnvoll erscheint z.B. alle 5 Minuten, also 00:05.
* '''configDir''' bietet die Möglichkeit, ein Verzeichnis zu definieren, in das HMInfo Dateien ablegen und von dem es die Dateien lesen wird. Default ist fhem_root.
* '''configFilename''' legt einen default Namen fest, der bei save und archive genutzt wird. Default ist regSave.cfg.
* '''hmAutoReadScan''' zeitinterval in Minuten, in denen CUL_HM prüft, ob offene autoRead bereitstehen und die IOs die Kapazität haben. Default ist 4 min.
== Weiterführende Links ==
* [[HomeMatic Templates]]

== Quellen ==
* Thread [http://forum.fhem.de/index.php?topic=11035.0 HMinfo] im FHEM Forum
* Thread {{Link2Forum|Topic=20119|LinkText=HMINfo, Intention, Sinn und Zweck}} im FHEM Forum

[[Kategorie:HomeMatic supportDevice]]
[[Kategorie:HOWTOS]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-01-09T08:29:56Z

Xaneu: /* Idee */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung, Akku-Spannung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-01-07T20:56:32Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Raspberry Pi: FHEM starten/stoppen

2020-01-06T16:03:52Z

Xaneu: /* Links */

Ein auf einem '''[[Raspberry Pi]]''' laufendes '''FHEM starten und stoppen''' (ein Neustart des Raspberry ist so nicht erforderlich).

== Voraussetzungen ==
* Funktionierender SSH Consolen Client
** MacOS X: Terminal.app
** Windows: openssh mit mingw (Putty kann auch genutzt werden, dabei funktioniert in den Beispielen Schritt 2 anders)
** Linux: ssh in der Shell

== FHEM starten ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo systemctl start fhem'' (bei älteren Rasbian-Versionen: ''sudo /etc/init.d/fhem start'') ausführen
Als Rückmeldung wird auf der Konsole "Starting fhem ..." ausgegeben. Damit ist FHEM gestartet. Als Gegenprüfung kann der Status abgefragt werden. Siehe "FHEM Status"

== FHEM stoppen ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo systemctl stop fhem'' (bei älteren Rasbian-Versionen: ''sudo /etc/init.d/fhem stop'') ausführen
Als Rückmeldung wird auf der Konsole "Stopping fhem ..." ausgegeben. Damit ist FHEM beendet. Als Gegenprüfung kann der Status abgefragt werden. Siehe "FHEM Status"

== FHEM Status ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo systemctl status fhem'' (bei älteren Rasbian-Versionen: ''sudo /etc/init.d/fhem status'') ausführen
Als Antwort wird auf der Konsole der aktuelle Status von FHEM ausgegeben. z.B. fhem is running

== Links ==
* Ausführlichere Anleitung, die auch für Raspberry hilfreich sein kann: [[FritzBox: FHEM per Telnet starten]]
* Auswahl sinnvoller [[Kommandozeilentools]]

[[Kategorie:FAQ]]
[[Kategorie:HOWTOS]]
[[Kategorie:Raspberry Pi]]

Raspberry Pi: FHEM starten/stoppen

2020-01-05T20:52:36Z

Xaneu: /* FHEM Status */

Raspberry Pi: FHEM starten/stoppen

2020-01-05T20:51:44Z

Xaneu: /* FHEM stoppen */

Ein auf einem '''[[Raspberry Pi]]''' laufendes '''FHEM starten und stoppen''' (ein Neustart des Raspberry ist so nicht erforderlich).

== Voraussetzungen ==
* Funktionierender SSH Consolen Client
** MacOS X: Terminal.app
** Windows: openssh mit mingw (Putty kann auch genutzt werden, dabei funktioniert in den Beispielen Schritt 2 anders)
** Linux: ssh in der Shell

== FHEM starten ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo systemctl start fhem'' (bei älteren Rasbian-Versionen: ''sudo /etc/init.d/fhem start'') ausführen
Als Rückmeldung wird auf der Konsole "Starting fhem ..." ausgegeben. Damit ist FHEM gestartet. Als Gegenprüfung kann der Status abgefragt werden. Siehe "FHEM Status"

== FHEM stoppen ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo systemctl stop fhem'' (bei älteren Rasbian-Versionen: ''sudo /etc/init.d/fhem stop'') ausführen
Als Rückmeldung wird auf der Konsole "Stopping fhem ..." ausgegeben. Damit ist FHEM beendet. Als Gegenprüfung kann der Status abgefragt werden. Siehe "FHEM Status"

== FHEM Status ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo /etc/init.d/fhem status'' ausführen
Als Antwort wird auf der Konsole der aktuelle Status von FHEM ausgegeben. z.B. fhem is running

== Links ==
* Ausführlichere Anleitung, die auch für Raspberry hilfreich sein kann: [[FritzBox: FHEM per Telnet starten]]
* Auswahl sinnvoller [[Kommandozeilentools]]

[[Kategorie:FAQ]]
[[Kategorie:HOWTOS]]

Raspberry Pi: FHEM starten/stoppen

2020-01-05T20:50:31Z

Xaneu: /* FHEM starten */

Ein auf einem '''[[Raspberry Pi]]''' laufendes '''FHEM starten und stoppen''' (ein Neustart des Raspberry ist so nicht erforderlich).

== Voraussetzungen ==
* Funktionierender SSH Consolen Client
** MacOS X: Terminal.app
** Windows: openssh mit mingw (Putty kann auch genutzt werden, dabei funktioniert in den Beispielen Schritt 2 anders)
** Linux: ssh in der Shell

== FHEM starten ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo systemctl start fhem'' (bei älteren Rasbian-Versionen: ''sudo /etc/init.d/fhem start'') ausführen
Als Rückmeldung wird auf der Konsole "Starting fhem ..." ausgegeben. Damit ist FHEM gestartet. Als Gegenprüfung kann der Status abgefragt werden. Siehe "FHEM Status"

== FHEM stoppen ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo /etc/init.d/fhem stop'' ausführen
Als Rückmeldung wird auf der Konsole "Stopping fhem ..." ausgegeben. Damit ist FHEM beendet. Als Gegenprüfung kann der Status abgefragt werden. Siehe "FHEM Status"

== FHEM Status ==
# Starten des SSH Clients
# Mit dem RPi verbinden mittels ''ssh pi@192.168.2.50'' (Hier muss natürlich der eigene User und IP eingegeben werden.)
# Passwort des Benutzers (in diesem Beispiel "pi") eingeben.
# Den Befehl ''sudo /etc/init.d/fhem status'' ausführen
Als Antwort wird auf der Konsole der aktuelle Status von FHEM ausgegeben. z.B. fhem is running

== Links ==
* Ausführlichere Anleitung, die auch für Raspberry hilfreich sein kann: [[FritzBox: FHEM per Telnet starten]]
* Auswahl sinnvoller [[Kommandozeilentools]]

[[Kategorie:FAQ]]
[[Kategorie:HOWTOS]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-01-01T18:26:34Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung");
}
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2020-01-01T18:24:35Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung="";

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
if ($usv_meldung ne "") {
fhem("set USV_Meldung $usv_meldung")
};
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-07-11T21:43:36Z

Xaneu: /* Ausblick */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Kategorie:Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-07-11T21:43:00Z

Xaneu: /* Ausblick */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]
[[Raspberry Pi]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-07-02T06:22:09Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss das I2C-Interface Modul „RPII2C“ zuvor definiert werden (siehe Commandref).

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-30T19:48:05Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-28T05:40:08Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi != 0xFF)
{
$status=$s_pi & 0x3F;
}

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-28T05:34:10Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $s_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$s_pi = $1;
if ($s_pi!=255)
{
status=$s_pi & 63;
}

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-19T19:53:59Z

Xaneu: /* Idee */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben (https://www.reichelt.de/raspberry-pi-usv-rpi-usv-p169883.html). 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-19T19:43:51Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben. 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung: 
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden. 
Der Wert des Statusregister wird hier als Dezimalzahl dargestellt und muss zur weiteren Verarbeitung ggf. noch binär ausdekodiert werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Homematic-Register von A-Z (Namen, Erklärung)

2019-06-12T21:53:41Z

Xaneu: /* energyOpt */

{{Baustelle}}
Dieser Artikel soll die Namensgebung der Homematic-Register erklären und einen Index aller bekannten Register mit einer kurzen Funktionserklärung liefern. Der Index folgt dabei den Registerklassen, da sich die Namensgebung diesbezüglich ebenfalls unterscheidet.

Zur grundsätzlichen Anwendung von Registerprogrammierung mit einigen Beispielen siehe u.a. den Artikel [[HomeMatic Register programmieren]] und [[HomeMatic HmInfo Templates erstellen]].

== Einführung ==

Die Namenskonvention der Homematic-Register ist für den Neuling verwirrend, folgt jedoch fast durchgängig einer einfachen Logik
* er setzt sich aus einem oder mehreren Bestandteilen zusammen
* er beginnt immer mit einem Kleinbuchstaben
* jeder weitere Namensbestandteil beginnt mit einem Großbuchstaben
* die Bezeichnungen der Bestandteile sind englisch, kurze Begriffe werden ausgeschrieben, längere abgekürzt

Die möglichen Bestandteile werden in den jeweiligen Registergruppen (Listen) erläutert.

Details zu den Wertebereichen sowie eine kurze englische Beschreibung liefert der Befehl '''reglist''' in Geräten und Kanälen.

== Die Registerklassen (Listen) eines Homematic-Gerätes ==

''Designvorschlag 1: Unterkapitel mit Inhaltsverzeichniseintrag''

Jedes Homematic-Gerät besitzt prinzipiell geräte-, kanal- und verknüpfungsbezogene Register. Bei Geräten, die nur einen sogenannten Kanal besitzen, erscheinen alle drei Register gemeinsam in der Definitionsansicht und den Listings in FHEM, bei Geräten mit mehreren Kanälen findet man die verknüfungs- und kanalbezogenen Register in den jeweiligen Kanälen.

=== Gerätebezogene Register ===
Gerätebezogene Register existieren für jedes HomeMatic-Gerät nur einmal und werden in der sogenannten '''List0''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_00.'' zu finden).

==== brightness====
brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].

==== energyOpt ====
energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich "permanent" (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].

''Designvorschlag 2: Tabelle''

{| class="wikitable"
|-
! Register !! Erläuterungen
|-
| brightness || brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].
|-
| confBtnTime || configuration button timeout. Wertangabe in Minuten (!) oder ''permanent'' Nicht immer sind die internen Tasten eines Gerätes ohne weiteres mit Aktionen für kurzen und langen Tastendruck programmierbar. Bei allen Hutschienen-Aktoren sowie den Zwischensteckern (mit nur einem Bedienknopf) versetzt ein langer Tastendruck (4 Sekunden) den Schalter normalerweise in den Konfigurations- bzw. Anlern-Modus, bei den in Unterputzdosen versenkbaren Schalt- und Dimmaktoren (-FM ohne PBU in der Bezeichnung) ohne eigenen Konfigurations-Button gilt dies sogar für die zur normalen Funktion extern angeschlossenen Taster. Dieses Verhalten kann man mit dem Register ''confBtnTime'' beeinflussen. Bis zum Ablauf der dort einstellbaren Zeit (in Minuten) nach dem Versorgen mit Strom (''powerUp'') erreicht man den Konfigurationsmodus wie bisher, danach interpretiert der Aktor die Tastendrücke stets als kurz (short) oder lang (long).
|-
| energyOpt || energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich ''permanent'' (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].
|-
| intKeyVisib || internal key(s) visible = interne Taste(n) sichtbar. Werte: ''visib'' = sichtbar bzw. ''invisib'' = unsichtbar (voreingestellt). Die internen "Tasten" eines Aktors (z.B. die Schaltwippe bei Wandschaltern/-tastern, der Bedienknopf bei Zwischensteckern, aber auch die angeschlossenen externen Taster bei Aktoren für Unterputzdosen oder die von außen zugängliche "Notbedientaste" etwa bei Zwischendecken-Dimmern) sind logisch ebenso mit dem Aktor verknüpft wie externe Bedienelemente wie Funkfernbedienungen oder per Funk verknüpfte Wandtaster. Ihre Betätigung wird (außer mit präparierter Firmware) zwar nicht gesendet (und kann daher von FHEM nicht "gelesen" werden), die vom Hersteller vorgesehenen Funktionen lassen sich aber genauso frei programmieren. Allerdings sind diese internen Verknüpfungen zur Vermeidung versehentlicher Programmierungen zunächst verborgen und müssen daher vor einer Manipulation explizit sichtbar gemacht werden.
|-
| ledMode || led modus = LED-Betriebsart, ''on'' bzw. ''off''. Die (batteriebetriebenen) -PCB-Aktoren und die 8-Kanal-Module haben kleine LED an Bord, die für Diagnosezwecke hilfreich sind, einem sparsamen Betrieb aber in der Regel entgegenstehen. Sie werden daher nur bei außergewöhnlichen Zuständen wie dem Anlernmodus, einem Reset, oder auch bei niedriger Batteriespannung als Hinweis an den Anwender benutzt und sind ansonsten ab Werk deaktiviert. Bei einer Dauerstromversorgung kann aber eine Schaltzustandsanzeige oder eine Quittung über eine Befehlsaussendung nicht nur zur Diagnose hilfreich sein. Die LED(s)zeigen dann bei Aktoren, ob der Aktor eingeschaltet ist (blinkend, wenn eine Einschaltzeitbegrenzung aktiv ist), und bei den Sensormodulen [[HM-MOD-EM-8_8-Kanal-Sendemodul|HM-Mod-EM-8]] und [[HM-MOD-EM-8bit_3-Kanal-Sendemodul_mit_8-Bit-Datenkanal|HM-Mod-EM-8bit]] zeigt die zweifarbige LED den von Fernbedienungen bekannten Sendezustand mit gelb, dem dann ein grün oder rot folgt - je nachdem ob eine Quittung angefordert ist und ob sie erfolgreich empfangen wurde.
|-
| localResDis || local reset disabled = Zurücksetzen am Gerät unmöglich. '''on''' bedeutet, dass das Gerät nicht mehr mit der Konfigurationstaste zurückgesetzt werden kann. '''off'' = Reset möglich (voreingestellt)
|-
| pairCentral || pairing to cental = angelernt an Zentrale. Wert wird hexadezimal dargestellt (000000 bis FFFFFF). 0 bedeutet, dass das Gerät nicht gepairt ist, anderenfalls ist der Wert die [[hmId]] der Zentrale.
|-
|}

=== Kanalbezogene Register ===
Kanalbezogene Register existieren für jeden Kanal eines Gerätes einmal und werden in der sogenannten '''List1''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_01.'' zu finden).

(to be continued). Beispiele: sign, dblPress, longPress, expectAES, peerNeedsBurst, ...

=== Platzhalter für Erklärung der List2 ===

=== Verknüpfungsbezogene Register ===
Diese Register sind am umfangreichsten und werden für jeden Verknüpfungspartner (peer) einzeln separat angelegt in der '''List3''' (''RegL_03.<peer>''). Die grundsätzlichen Funktionen und ihre Zusammenhänge sind auch ausführlich in der Einsteigerdokumentation erklärt, inklusive Skizzen für die sogenannte ''state machine''.

Diese Register regeln das Verhalten eines Aktors beim Erhalt eines sog. Triggers. Tastensensoren senden ''short''- und (automatisch wiederholte) ''long''-Trigger bei kurzen bzw. längeren Tastendrücken. Für beide Arten gibt es relativ ähnliche Registergruppen, die genau festlegen, in welchem Zustand welcher Trigger welche Aktion auslöst. Einen Sonderfall stellen Zustandsmelder dar (Fensterkontakte, Schaltkontaktinterfaces, aber auch Bewegungsmelder), die einmalige Trigger mit einem Wert zwischen 0 und 200 senden. Für diese gelten ebenfalls die short-Registersätze.

Jedes Register setzt sich prinzipiell also zusammen
* aus einer Unterscheidung, ob sie für short- oder long-Trigger gelten (sh bzw. lg)
* Aktionswunsch (action) / Bedingung (condition, ct) / Sprungquelle (DimJt bzw. SwJt bei Dimmer/Schaltern) oder Zustand (Off, OnDly, RampOn, On, OffDly, RampOff)
* der eigentlichen Einstellungsmöglichkeit (Variable)
Der zugewiesene Registerwert steuert dann die Aktion entsprechend.

=== Platzhalter für weitere Listen ===

'''TEXTBAUSTEINSPEICHER (wird entfernt)'''

Mögliche Aktionstypen bei Tastendruck:
- off: Es erfolgt keine Aktion
- downDim: Herunterdimmen bei langem Tastendruck (peer dual)
- upDim: Hochdimmen bei langem Tastendruck (peer dual
- toggleDim: Herunter.oder Hochdimmen bei langem Tastendruck, wechselt (Eintastenb, peer single)
- jmpToTarget: Springe zum definierten Sprungziel
- toggleDimToCntInv?
- toggleDimToCnt?
- toggleToCntInv?
- toggleToCnt?
Triggerschwellen für Werte (jeweils zwei für short und long-Trigger)
- [sh|lg]CtValHi: hoher Triggerwert (High) für Short/Long (0-255, normal 100)
- [sh|lg]CtValLo: niedriger Triggerwert (Low) für Short/Long (0-255, normal 50)
Mögliche Bedingungen für einen Trigger (Trigger ist erfüllt, wenn bereitgestellter Wert …)
- ltLo/ltHi (less than low/high): niedriger als Low/High
- geLo/geHi (greater than or equal low/high) gleich oder höher als High
- between: zwischen Low und High, also über/gleich Low und kleiner/gleich High
- outside: kleiner als Low und größer als High
Die Triggerbedingungen gibt es getrennt für jeden aktuellen Zustand des Dimm-Aktors:
- [sh|lg]Ct[Off|DlyOn|RampOn|On|DlyOff|RampOff|Off], insgesamt 12
Sprungquellen und Sprungziele: Bei Eintreffen eines gültigen Triggers wird von einem Zustand in einen anderen Zustand gesprungen. Hier gibt es
- DimJt...

Relevante ähnliche Informationen / Details hier: [https://homematic-forum.de/forum/viewtopic.php?t=7508 Expertenmode: Aktionstypen bei einer Direktverknüpfung]

[[Kategorie:HomeMatic Components]]

Homematic-Register von A-Z (Namen, Erklärung)

2019-06-12T21:52:52Z

Xaneu: /* energyOpt */

{{Baustelle}}
Dieser Artikel soll die Namensgebung der Homematic-Register erklären und einen Index aller bekannten Register mit einer kurzen Funktionserklärung liefern. Der Index folgt dabei den Registerklassen, da sich die Namensgebung diesbezüglich ebenfalls unterscheidet.

Zur grundsätzlichen Anwendung von Registerprogrammierung mit einigen Beispielen siehe u.a. den Artikel [[HomeMatic Register programmieren]] und [[HomeMatic HmInfo Templates erstellen]].

== Einführung ==

Die Namenskonvention der Homematic-Register ist für den Neuling verwirrend, folgt jedoch fast durchgängig einer einfachen Logik
* er setzt sich aus einem oder mehreren Bestandteilen zusammen
* er beginnt immer mit einem Kleinbuchstaben
* jeder weitere Namensbestandteil beginnt mit einem Großbuchstaben
* die Bezeichnungen der Bestandteile sind englisch, kurze Begriffe werden ausgeschrieben, längere abgekürzt

Die möglichen Bestandteile werden in den jeweiligen Registergruppen (Listen) erläutert.

Details zu den Wertebereichen sowie eine kurze englische Beschreibung liefert der Befehl '''reglist''' in Geräten und Kanälen.

== Die Registerklassen (Listen) eines Homematic-Gerätes ==

''Designvorschlag 1: Unterkapitel mit Inhaltsverzeichniseintrag''

Jedes Homematic-Gerät besitzt prinzipiell geräte-, kanal- und verknüpfungsbezogene Register. Bei Geräten, die nur einen sogenannten Kanal besitzen, erscheinen alle drei Register gemeinsam in der Definitionsansicht und den Listings in FHEM, bei Geräten mit mehreren Kanälen findet man die verknüfungs- und kanalbezogenen Register in den jeweiligen Kanälen.

=== Gerätebezogene Register ===
Gerätebezogene Register existieren für jedes HomeMatic-Gerät nur einmal und werden in der sogenannten '''List0''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_00.'' zu finden).

==== brightness====
brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].

==== energyOpt ====
energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich "permanent" (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].

''Designvorschlag 2: Tabelle''

{| class="wikitable"
|-
! Register !! Erläuterungen
|-
| brightness || brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].
|-
| confBtnTime || configuration button timeout. Wertangabe in Minuten (!) oder ''permanent'' Nicht immer sind die internen Tasten eines Gerätes ohne weiteres mit Aktionen für kurzen und langen Tastendruck programmierbar. Bei allen Hutschienen-Aktoren sowie den Zwischensteckern (mit nur einem Bedienknopf) versetzt ein langer Tastendruck (4 Sekunden) den Schalter normalerweise in den Konfigurations- bzw. Anlern-Modus, bei den in Unterputzdosen versenkbaren Schalt- und Dimmaktoren (-FM ohne PBU in der Bezeichnung) ohne eigenen Konfigurations-Button gilt dies sogar für die zur normalen Funktion extern angeschlossenen Taster. Dieses Verhalten kann man mit dem Register ''confBtnTime'' beeinflussen. Bis zum Ablauf der dort einstellbaren Zeit (in Minuten) nach dem Versorgen mit Strom (''powerUp'') erreicht man den Konfigurationsmodus wie bisher, danach interpretiert der Aktor die Tastendrücke stets als kurz (short) oder lang (long).
|-
| energyOpt || energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich ''permanent'' (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].
|-
| intKeyVisib || internal key(s) visible = interne Taste(n) sichtbar. Werte: ''visib'' = sichtbar bzw. ''invisib'' = unsichtbar (voreingestellt). Die internen "Tasten" eines Aktors (z.B. die Schaltwippe bei Wandschaltern/-tastern, der Bedienknopf bei Zwischensteckern, aber auch die angeschlossenen externen Taster bei Aktoren für Unterputzdosen oder die von außen zugängliche "Notbedientaste" etwa bei Zwischendecken-Dimmern) sind logisch ebenso mit dem Aktor verknüpft wie externe Bedienelemente wie Funkfernbedienungen oder per Funk verknüpfte Wandtaster. Ihre Betätigung wird (außer mit präparierter Firmware) zwar nicht gesendet (und kann daher von FHEM nicht "gelesen" werden), die vom Hersteller vorgesehenen Funktionen lassen sich aber genauso frei programmieren. Allerdings sind diese internen Verknüpfungen zur Vermeidung versehentlicher Programmierungen zunächst verborgen und müssen daher vor einer Manipulation explizit sichtbar gemacht werden.
|-
| ledMode || led modus = LED-Betriebsart, ''on'' bzw. ''off''. Die (batteriebetriebenen) -PCB-Aktoren und die 8-Kanal-Module haben kleine LED an Bord, die für Diagnosezwecke hilfreich sind, einem sparsamen Betrieb aber in der Regel entgegenstehen. Sie werden daher nur bei außergewöhnlichen Zuständen wie dem Anlernmodus, einem Reset, oder auch bei niedriger Batteriespannung als Hinweis an den Anwender benutzt und sind ansonsten ab Werk deaktiviert. Bei einer Dauerstromversorgung kann aber eine Schaltzustandsanzeige oder eine Quittung über eine Befehlsaussendung nicht nur zur Diagnose hilfreich sein. Die LED(s)zeigen dann bei Aktoren, ob der Aktor eingeschaltet ist (blinkend, wenn eine Einschaltzeitbegrenzung aktiv ist), und bei den Sensormodulen [[HM-MOD-EM-8_8-Kanal-Sendemodul|HM-Mod-EM-8]] und [[HM-MOD-EM-8bit_3-Kanal-Sendemodul_mit_8-Bit-Datenkanal|HM-Mod-EM8bit]] zeigt die zweifarbige LED den von Fernbedienungen bekannten Sendezustand mit gelb, dem dann ein grün oder rot folgt - je nachdem ob eine Quittung angefordert ist und ob sie erfolgreich empfangen wurde.
|-
| localResDis || local reset disabled = Zurücksetzen am Gerät unmöglich. '''on''' bedeutet, dass das Gerät nicht mehr mit der Konfigurationstaste zurückgesetzt werden kann. '''off'' = Reset möglich (voreingestellt)
|-
| pairCentral || pairing to cental = angelernt an Zentrale. Wert wird hexadezimal dargestellt (000000 bis FFFFFF). 0 bedeutet, dass das Gerät nicht gepairt ist, anderenfalls ist der Wert die [[hmId]] der Zentrale.
|-
|}

=== Kanalbezogene Register ===
Kanalbezogene Register existieren für jeden Kanal eines Gerätes einmal und werden in der sogenannten '''List1''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_01.'' zu finden).

(to be continued). Beispiele: sign, dblPress, longPress, expectAES, peerNeedsBurst, ...

=== Platzhalter für Erklärung der List2 ===

=== Verknüpfungsbezogene Register ===
Diese Register sind am umfangreichsten und werden für jeden Verknüpfungspartner (peer) einzeln separat angelegt in der '''List3''' (''RegL_03.<peer>''). Die grundsätzlichen Funktionen und ihre Zusammenhänge sind auch ausführlich in der Einsteigerdokumentation erklärt, inklusive Skizzen für die sogenannte ''state machine''.

Diese Register regeln das Verhalten eines Aktors beim Erhalt eines sog. Triggers. Tastensensoren senden ''short''- und (automatisch wiederholte) ''long''-Trigger bei kurzen bzw. längeren Tastendrücken. Für beide Arten gibt es relativ ähnliche Registergruppen, die genau festlegen, in welchem Zustand welcher Trigger welche Aktion auslöst. Einen Sonderfall stellen Zustandsmelder dar (Fensterkontakte, Schaltkontaktinterfaces, aber auch Bewegungsmelder), die einmalige Trigger mit einem Wert zwischen 0 und 200 senden. Für diese gelten ebenfalls die short-Registersätze.

Jedes Register setzt sich prinzipiell also zusammen
* aus einer Unterscheidung, ob sie für short- oder long-Trigger gelten (sh bzw. lg)
* Aktionswunsch (action) / Bedingung (condition, ct) / Sprungquelle (DimJt bzw. SwJt bei Dimmer/Schaltern) oder Zustand (Off, OnDly, RampOn, On, OffDly, RampOff)
* der eigentlichen Einstellungsmöglichkeit (Variable)
Der zugewiesene Registerwert steuert dann die Aktion entsprechend.

=== Platzhalter für weitere Listen ===

'''TEXTBAUSTEINSPEICHER (wird entfernt)'''

Mögliche Aktionstypen bei Tastendruck:
- off: Es erfolgt keine Aktion
- downDim: Herunterdimmen bei langem Tastendruck (peer dual)
- upDim: Hochdimmen bei langem Tastendruck (peer dual
- toggleDim: Herunter.oder Hochdimmen bei langem Tastendruck, wechselt (Eintastenb, peer single)
- jmpToTarget: Springe zum definierten Sprungziel
- toggleDimToCntInv?
- toggleDimToCnt?
- toggleToCntInv?
- toggleToCnt?
Triggerschwellen für Werte (jeweils zwei für short und long-Trigger)
- [sh|lg]CtValHi: hoher Triggerwert (High) für Short/Long (0-255, normal 100)
- [sh|lg]CtValLo: niedriger Triggerwert (Low) für Short/Long (0-255, normal 50)
Mögliche Bedingungen für einen Trigger (Trigger ist erfüllt, wenn bereitgestellter Wert …)
- ltLo/ltHi (less than low/high): niedriger als Low/High
- geLo/geHi (greater than or equal low/high) gleich oder höher als High
- between: zwischen Low und High, also über/gleich Low und kleiner/gleich High
- outside: kleiner als Low und größer als High
Die Triggerbedingungen gibt es getrennt für jeden aktuellen Zustand des Dimm-Aktors:
- [sh|lg]Ct[Off|DlyOn|RampOn|On|DlyOff|RampOff|Off], insgesamt 12
Sprungquellen und Sprungziele: Bei Eintreffen eines gültigen Triggers wird von einem Zustand in einen anderen Zustand gesprungen. Hier gibt es
- DimJt...

Relevante ähnliche Informationen / Details hier: [https://homematic-forum.de/forum/viewtopic.php?t=7508 Expertenmode: Aktionstypen bei einer Direktverknüpfung]

[[Kategorie:HomeMatic Components]]

Homematic-Register von A-Z (Namen, Erklärung)

2019-06-12T21:51:24Z

Xaneu: /* energyOpt */

{{Baustelle}}
Dieser Artikel soll die Namensgebung der Homematic-Register erklären und einen Index aller bekannten Register mit einer kurzen Funktionserklärung liefern. Der Index folgt dabei den Registerklassen, da sich die Namensgebung diesbezüglich ebenfalls unterscheidet.

Zur grundsätzlichen Anwendung von Registerprogrammierung mit einigen Beispielen siehe u.a. den Artikel [[HomeMatic Register programmieren]] und [[HomeMatic HmInfo Templates erstellen]].

== Einführung ==

Die Namenskonvention der Homematic-Register ist für den Neuling verwirrend, folgt jedoch fast durchgängig einer einfachen Logik
* er setzt sich aus einem oder mehreren Bestandteilen zusammen
* er beginnt immer mit einem Kleinbuchstaben
* jeder weitere Namensbestandteil beginnt mit einem Großbuchstaben
* die Bezeichnungen der Bestandteile sind englisch, kurze Begriffe werden ausgeschrieben, längere abgekürzt

Die möglichen Bestandteile werden in den jeweiligen Registergruppen (Listen) erläutert.

Details zu den Wertebereichen sowie eine kurze englische Beschreibung liefert der Befehl '''reglist''' in Geräten und Kanälen.

== Die Registerklassen (Listen) eines Homematic-Gerätes ==

''Designvorschlag 1: Unterkapitel mit Inhaltsverzeichniseintrag''

Jedes Homematic-Gerät besitzt prinzipiell geräte-, kanal- und verknüpfungsbezogene Register. Bei Geräten, die nur einen sogenannten Kanal besitzen, erscheinen alle drei Register gemeinsam in der Definitionsansicht und den Listings in FHEM, bei Geräten mit mehreren Kanälen findet man die verknüfungs- und kanalbezogenen Register in den jeweiligen Kanälen.

=== Gerätebezogene Register ===
Gerätebezogene Register existieren für jedes HomeMatic-Gerät nur einmal und werden in der sogenannten '''List0''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_00.'' zu finden).

==== brightness====
brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].

==== energyOpt ====
energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich "permanent" (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].

''Designvorschlag 2: Tabelle''

{| class="wikitable"
|-
! Register !! Erläuterungen
|-
| brightness || brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].
|-
| confBtnTime || configuration button timeout. Wertangabe in Minuten (!) oder ''permanent'' Nicht immer sind die internen Tasten eines Gerätes ohne weiteres mit Aktionen für kurzen und langen Tastendruck programmierbar. Bei allen Hutschienen-Aktoren sowie den Zwischensteckern (mit nur einem Bedienknopf) versetzt ein langer Tastendruck (4 Sekunden) den Schalter normalerweise in den Konfigurations- bzw. Anlern-Modus, bei den in Unterputzdosen versenkbaren Schalt- und Dimmaktoren (-FM ohne PBU in der Bezeichnung) ohne eigenen Konfigurations-Button gilt dies sogar für die zur normalen Funktion extern angeschlossenen Taster. Dieses Verhalten kann man mit dem Register ''confBtnTime'' beeinflussen. Bis zum Ablauf der dort einstellbaren Zeit (in Minuten) nach dem Versorgen mit Strom (''powerUp'') erreicht man den Konfigurationsmodus wie bisher, danach interpretiert der Aktor die Tastendrücke stets als kurz (short) oder lang (long).
|-
| energyOpt || energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich ''permanent'' (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].
|-
| intKeyVisib || internal key(s) visible = interne Taste(n) sichtbar. Werte: ''visib'' = sichtbar bzw. ''invisib'' = unsichtbar (voreingestellt). Die internen "Tasten" eines Aktors (z.B. die Schaltwippe bei Wandschaltern/-tastern, der Bedienknopf bei Zwischensteckern, aber auch die angeschlossenen externen Taster bei Aktoren für Unterputzdosen oder die von außen zugängliche "Notbedientaste" etwa bei Zwischendecken-Dimmern) sind logisch ebenso mit dem Aktor verknüpft wie externe Bedienelemente wie Funkfernbedienungen oder per Funk verknüpfte Wandtaster. Ihre Betätigung wird (außer mit präparierter Firmware) zwar nicht gesendet (und kann daher von FHEM nicht "gelesen" werden), die vom Hersteller vorgesehenen Funktionen lassen sich aber genauso frei programmieren. Allerdings sind diese internen Verknüpfungen zur Vermeidung versehentlicher Programmierungen zunächst verborgen und müssen daher vor einer Manipulation explizit sichtbar gemacht werden.
|-
| ledMode || led modus = LED-Betriebsart, ''on'' bzw. ''off''. Die (batteriebetriebenen) -PCB-Aktoren und die 8-Kanal-Module haben kleine LED an Bord, die für Diagnosezwecke hilfreich sind, einem sparsamen Betrieb aber in der Regel entgegenstehen. Sie werden daher nur bei außergewöhnlichen Zuständen wie dem Anlernmodus, einem Reset, oder auch bei niedriger Batteriespannung als Hinweis an den Anwender benutzt und sind ansonsten ab Werk deaktiviert. Bei einer Dauerstromversorgung kann aber eine Schaltzustandsanzeige oder eine Quittung über eine Befehlsaussendung nicht nur zur Diagnose hilfreich sein. Die LED(s)zeigen dann bei Aktoren, ob der Aktor eingeschaltet ist (blinkend, wenn eine Einschaltzeitbegrenzung aktiv ist), und bei den Sensormodulen [[HM-MOD-EM-8_8-Kanal-Sendemodul|HM-Mod-EM8]] und [[HM-MOD-EM-8bit_3-Kanal-Sendemodul_mit_8-Bit-Datenkanal|HM-Mod-EM8bit]] zeigt die zweifarbige LED den von Fernbedienungen bekannten Sendezustand mit gelb, dem dann ein grün oder rot folgt - je nachdem ob eine Quittung angefordert ist und ob sie erfolgreich empfangen wurde.
|-
| localResDis || local reset disabled = Zurücksetzen am Gerät unmöglich. '''on''' bedeutet, dass das Gerät nicht mehr mit der Konfigurationstaste zurückgesetzt werden kann. '''off'' = Reset möglich (voreingestellt)
|-
| pairCentral || pairing to cental = angelernt an Zentrale. Wert wird hexadezimal dargestellt (000000 bis FFFFFF). 0 bedeutet, dass das Gerät nicht gepairt ist, anderenfalls ist der Wert die [[hmId]] der Zentrale.
|-
|}

=== Kanalbezogene Register ===
Kanalbezogene Register existieren für jeden Kanal eines Gerätes einmal und werden in der sogenannten '''List1''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_01.'' zu finden).

(to be continued). Beispiele: sign, dblPress, longPress, expectAES, peerNeedsBurst, ...

=== Platzhalter für Erklärung der List2 ===

=== Verknüpfungsbezogene Register ===
Diese Register sind am umfangreichsten und werden für jeden Verknüpfungspartner (peer) einzeln separat angelegt in der '''List3''' (''RegL_03.<peer>''). Die grundsätzlichen Funktionen und ihre Zusammenhänge sind auch ausführlich in der Einsteigerdokumentation erklärt, inklusive Skizzen für die sogenannte ''state machine''.

Diese Register regeln das Verhalten eines Aktors beim Erhalt eines sog. Triggers. Tastensensoren senden ''short''- und (automatisch wiederholte) ''long''-Trigger bei kurzen bzw. längeren Tastendrücken. Für beide Arten gibt es relativ ähnliche Registergruppen, die genau festlegen, in welchem Zustand welcher Trigger welche Aktion auslöst. Einen Sonderfall stellen Zustandsmelder dar (Fensterkontakte, Schaltkontaktinterfaces, aber auch Bewegungsmelder), die einmalige Trigger mit einem Wert zwischen 0 und 200 senden. Für diese gelten ebenfalls die short-Registersätze.

Jedes Register setzt sich prinzipiell also zusammen
* aus einer Unterscheidung, ob sie für short- oder long-Trigger gelten (sh bzw. lg)
* Aktionswunsch (action) / Bedingung (condition, ct) / Sprungquelle (DimJt bzw. SwJt bei Dimmer/Schaltern) oder Zustand (Off, OnDly, RampOn, On, OffDly, RampOff)
* der eigentlichen Einstellungsmöglichkeit (Variable)
Der zugewiesene Registerwert steuert dann die Aktion entsprechend.

=== Platzhalter für weitere Listen ===

'''TEXTBAUSTEINSPEICHER (wird entfernt)'''

Mögliche Aktionstypen bei Tastendruck:
- off: Es erfolgt keine Aktion
- downDim: Herunterdimmen bei langem Tastendruck (peer dual)
- upDim: Hochdimmen bei langem Tastendruck (peer dual
- toggleDim: Herunter.oder Hochdimmen bei langem Tastendruck, wechselt (Eintastenb, peer single)
- jmpToTarget: Springe zum definierten Sprungziel
- toggleDimToCntInv?
- toggleDimToCnt?
- toggleToCntInv?
- toggleToCnt?
Triggerschwellen für Werte (jeweils zwei für short und long-Trigger)
- [sh|lg]CtValHi: hoher Triggerwert (High) für Short/Long (0-255, normal 100)
- [sh|lg]CtValLo: niedriger Triggerwert (Low) für Short/Long (0-255, normal 50)
Mögliche Bedingungen für einen Trigger (Trigger ist erfüllt, wenn bereitgestellter Wert …)
- ltLo/ltHi (less than low/high): niedriger als Low/High
- geLo/geHi (greater than or equal low/high) gleich oder höher als High
- between: zwischen Low und High, also über/gleich Low und kleiner/gleich High
- outside: kleiner als Low und größer als High
Die Triggerbedingungen gibt es getrennt für jeden aktuellen Zustand des Dimm-Aktors:
- [sh|lg]Ct[Off|DlyOn|RampOn|On|DlyOff|RampOff|Off], insgesamt 12
Sprungquellen und Sprungziele: Bei Eintreffen eines gültigen Triggers wird von einem Zustand in einen anderen Zustand gesprungen. Hier gibt es
- DimJt...

Relevante ähnliche Informationen / Details hier: [https://homematic-forum.de/forum/viewtopic.php?t=7508 Expertenmode: Aktionstypen bei einer Direktverknüpfung]

[[Kategorie:HomeMatic Components]]

Homematic-Register von A-Z (Namen, Erklärung)

2019-06-12T21:49:38Z

Xaneu: /* energyOpt */

{{Baustelle}}
Dieser Artikel soll die Namensgebung der Homematic-Register erklären und einen Index aller bekannten Register mit einer kurzen Funktionserklärung liefern. Der Index folgt dabei den Registerklassen, da sich die Namensgebung diesbezüglich ebenfalls unterscheidet.

Zur grundsätzlichen Anwendung von Registerprogrammierung mit einigen Beispielen siehe u.a. den Artikel [[HomeMatic Register programmieren]] und [[HomeMatic HmInfo Templates erstellen]].

== Einführung ==

Die Namenskonvention der Homematic-Register ist für den Neuling verwirrend, folgt jedoch fast durchgängig einer einfachen Logik
* er setzt sich aus einem oder mehreren Bestandteilen zusammen
* er beginnt immer mit einem Kleinbuchstaben
* jeder weitere Namensbestandteil beginnt mit einem Großbuchstaben
* die Bezeichnungen der Bestandteile sind englisch, kurze Begriffe werden ausgeschrieben, längere abgekürzt

Die möglichen Bestandteile werden in den jeweiligen Registergruppen (Listen) erläutert.

Details zu den Wertebereichen sowie eine kurze englische Beschreibung liefert der Befehl '''reglist''' in Geräten und Kanälen.

== Die Registerklassen (Listen) eines Homematic-Gerätes ==

''Designvorschlag 1: Unterkapitel mit Inhaltsverzeichniseintrag''

Jedes Homematic-Gerät besitzt prinzipiell geräte-, kanal- und verknüpfungsbezogene Register. Bei Geräten, die nur einen sogenannten Kanal besitzen, erscheinen alle drei Register gemeinsam in der Definitionsansicht und den Listings in FHEM, bei Geräten mit mehreren Kanälen findet man die verknüfungs- und kanalbezogenen Register in den jeweiligen Kanälen.

=== Gerätebezogene Register ===
Gerätebezogene Register existieren für jedes HomeMatic-Gerät nur einmal und werden in der sogenannten '''List0''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_00.'' zu finden).

==== brightness====
brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].

==== energyOpt ====
energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich "permanent" (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].

''Designvorschlag 2: Tabelle''

{| class="wikitable"
|-
! Register !! Erläuterungen
|-
| brightness || brightness = Helligkeit. Wertebereich: 0-15. Steuert die Helligkeit der LED-Anzeige. Verwendet in: [[HM-OU-LED16]].
|-
| confBtnTime || configuration button timeout. Wertangabe in Minuten (!) oder ''permanent'' Nicht immer sind die internen Tasten eines Gerätes ohne weiteres mit Aktionen für kurzen und langen Tastendruck programmierbar. Bei allen Hutschienen-Aktoren sowie den Zwischensteckern (mit nur einem Bedienknopf) versetzt ein langer Tastendruck (4 Sekunden) den Schalter normalerweise in den Konfigurations- bzw. Anlern-Modus, bei den in Unterputzdosen versenkbaren Schalt- und Dimmaktoren (-FM ohne PBU in der Bezeichnung) ohne eigenen Konfigurations-Button gilt dies sogar für die zur normalen Funktion extern angeschlossenen Taster. Dieses Verhalten kann man mit dem Register ''confBtnTime'' beeinflussen. Bis zum Ablauf der dort einstellbaren Zeit (in Minuten) nach dem Versorgen mit Strom (''powerUp'') erreicht man den Konfigurationsmodus wie bisher, danach interpretiert der Aktor die Tastendrücke stets als kurz (short) oder lang (long).
|-
| energyOpt || energy option = Energieoptionen. Wertebereich: 0 to 127 (Sekunden), zusätzlich ''permanent'' (dauerhaft). Einschaltdauer des Displays [[HM-OU-LED16]].
|-
| intKeyVisib || internal key(s) visible = interne Taste(n) sichtbar. Werte: ''visib'' = sichtbar bzw. ''invisib'' = unsichtbar (voreingestellt). Die internen "Tasten" eines Aktors (z.B. die Schaltwippe bei Wandschaltern/-tastern, der Bedienknopf bei Zwischensteckern, aber auch die angeschlossenen externen Taster bei Aktoren für Unterputzdosen oder die von außen zugängliche "Notbedientaste" etwa bei Zwischendecken-Dimmern) sind logisch ebenso mit dem Aktor verknüpft wie externe Bedienelemente wie Funkfernbedienungen oder per Funk verknüpfte Wandtaster. Ihre Betätigung wird (außer mit präparierter Firmware) zwar nicht gesendet (und kann daher von FHEM nicht "gelesen" werden), die vom Hersteller vorgesehenen Funktionen lassen sich aber genauso frei programmieren. Allerdings sind diese internen Verknüpfungen zur Vermeidung versehentlicher Programmierungen zunächst verborgen und müssen daher vor einer Manipulation explizit sichtbar gemacht werden.
|-
| ledMode || led modus = LED-Betriebsart, ''on'' bzw. ''off''. Die (batteriebetriebenen) -PCB-Aktoren und die 8-Kanal-Module haben kleine LED an Bord, die für Diagnosezwecke hilfreich sind, einem sparsamen Betrieb aber in der Regel entgegenstehen. Sie werden daher nur bei außergewöhnlichen Zuständen wie dem Anlernmodus, einem Reset, oder auch bei niedriger Batteriespannung als Hinweis an den Anwender benutzt und sind ansonsten ab Werk deaktiviert. Bei einer Dauerstromversorgung kann aber eine Schaltzustandsanzeige oder eine Quittung über eine Befehlsaussendung nicht nur zur Diagnose hilfreich sein. Die LED(s)zeigen dann bei Aktoren, ob der Aktor eingeschaltet ist (blinkend, wenn eine Einschaltzeitbegrenzung aktiv ist), und bei den Sensormodulen [[HM-MOD-EM-8_8-Kanal-Sendemodul|HM-Mod-EM8]] und [HM-Mod-EM8bit]] zeigt die zweifarbige LED den von Fernbedienungen bekannten Sendezustand mit gelb, dem dann ein grün oder rot folgt - je nachdem ob eine Quittung angefordert ist und ob sie erfolgreich empfangen wurde.
|-
| localResDis || local reset disabled = Zurücksetzen am Gerät unmöglich. '''on''' bedeutet, dass das Gerät nicht mehr mit der Konfigurationstaste zurückgesetzt werden kann. '''off'' = Reset möglich (voreingestellt)
|-
| pairCentral || pairing to cental = angelernt an Zentrale. Wert wird hexadezimal dargestellt (000000 bis FFFFFF). 0 bedeutet, dass das Gerät nicht gepairt ist, anderenfalls ist der Wert die [[hmId]] der Zentrale.
|-
|}

=== Kanalbezogene Register ===
Kanalbezogene Register existieren für jeden Kanal eines Gerätes einmal und werden in der sogenannten '''List1''' gespeichert (in der FHEM-Oberfläche als Hexbytefolge unter ''RegL_01.'' zu finden).

(to be continued). Beispiele: sign, dblPress, longPress, expectAES, peerNeedsBurst, ...

=== Platzhalter für Erklärung der List2 ===

=== Verknüpfungsbezogene Register ===
Diese Register sind am umfangreichsten und werden für jeden Verknüpfungspartner (peer) einzeln separat angelegt in der '''List3''' (''RegL_03.<peer>''). Die grundsätzlichen Funktionen und ihre Zusammenhänge sind auch ausführlich in der Einsteigerdokumentation erklärt, inklusive Skizzen für die sogenannte ''state machine''.

Diese Register regeln das Verhalten eines Aktors beim Erhalt eines sog. Triggers. Tastensensoren senden ''short''- und (automatisch wiederholte) ''long''-Trigger bei kurzen bzw. längeren Tastendrücken. Für beide Arten gibt es relativ ähnliche Registergruppen, die genau festlegen, in welchem Zustand welcher Trigger welche Aktion auslöst. Einen Sonderfall stellen Zustandsmelder dar (Fensterkontakte, Schaltkontaktinterfaces, aber auch Bewegungsmelder), die einmalige Trigger mit einem Wert zwischen 0 und 200 senden. Für diese gelten ebenfalls die short-Registersätze.

Jedes Register setzt sich prinzipiell also zusammen
* aus einer Unterscheidung, ob sie für short- oder long-Trigger gelten (sh bzw. lg)
* Aktionswunsch (action) / Bedingung (condition, ct) / Sprungquelle (DimJt bzw. SwJt bei Dimmer/Schaltern) oder Zustand (Off, OnDly, RampOn, On, OffDly, RampOff)
* der eigentlichen Einstellungsmöglichkeit (Variable)
Der zugewiesene Registerwert steuert dann die Aktion entsprechend.

=== Platzhalter für weitere Listen ===

'''TEXTBAUSTEINSPEICHER (wird entfernt)'''

Mögliche Aktionstypen bei Tastendruck:
- off: Es erfolgt keine Aktion
- downDim: Herunterdimmen bei langem Tastendruck (peer dual)
- upDim: Hochdimmen bei langem Tastendruck (peer dual
- toggleDim: Herunter.oder Hochdimmen bei langem Tastendruck, wechselt (Eintastenb, peer single)
- jmpToTarget: Springe zum definierten Sprungziel
- toggleDimToCntInv?
- toggleDimToCnt?
- toggleToCntInv?
- toggleToCnt?
Triggerschwellen für Werte (jeweils zwei für short und long-Trigger)
- [sh|lg]CtValHi: hoher Triggerwert (High) für Short/Long (0-255, normal 100)
- [sh|lg]CtValLo: niedriger Triggerwert (Low) für Short/Long (0-255, normal 50)
Mögliche Bedingungen für einen Trigger (Trigger ist erfüllt, wenn bereitgestellter Wert …)
- ltLo/ltHi (less than low/high): niedriger als Low/High
- geLo/geHi (greater than or equal low/high) gleich oder höher als High
- between: zwischen Low und High, also über/gleich Low und kleiner/gleich High
- outside: kleiner als Low und größer als High
Die Triggerbedingungen gibt es getrennt für jeden aktuellen Zustand des Dimm-Aktors:
- [sh|lg]Ct[Off|DlyOn|RampOn|On|DlyOff|RampOff|Off], insgesamt 12
Sprungquellen und Sprungziele: Bei Eintreffen eines gültigen Triggers wird von einem Zustand in einen anderen Zustand gesprungen. Hier gibt es
- DimJt...

Relevante ähnliche Informationen / Details hier: [https://homematic-forum.de/forum/viewtopic.php?t=7508 Expertenmode: Aktionstypen bei einer Direktverknüpfung]

[[Kategorie:HomeMatic Components]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-12T19:30:08Z

Xaneu:

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben. 
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-12T19:29:38Z

Xaneu:

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+ Foto: RITTER Elektronik GmbH]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell von Ritter Elektronik hergestellt wird, beschrieben. Die PIUSV+ wird über Reichelt Elektronik vertrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Kategorie:USV

2019-06-12T06:10:08Z

Xaneu:

Unterbrechungsfreie Stromversorgung (USV) ist für manche Zwecke der Hausautomatisierung eine extrem nützliche Angelegenheit.
*USV-Systeme mit genügend Leistung zur Versorgung von Desktop-Computern oder Servern liefern in der Regel 230 V Wechselspannung am Ausgang und sind über ein Interface abfragbar.
*Mini-USV-Systeme liefern Kleinspannung (5 - 48V) bei Leistungen von ca. 15 - 30 W, haben aber teilweise den Nachteil, kein Interface zu besitzen.
*USV-Zusätze für Einplatinencomputer wie den Raspberry Pi können meist direkt auf diese aufgesteckt werden, liefern aber nur wenige Watt Leistung.

[[Kategorie:Hardware Typen]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-11T20:24:00Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-11T20:22:24Z

Xaneu: /* Umsetzung */

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-11T20:21:30Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Datagramm
define USV_Datagramm dummy

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Statusregister
define USV_Statusregister dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-11T20:18:51Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $datagramm;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $status;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$datagramm=$content
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";

fhem("set PIi2c_1 writeByte 18 00");
$content=fhem("get PIi2c_1 read 18",1);
$content=~ m/received : (\d+) |/is;
$status = $1;

fhem("set USV_Datagramm $datagramm");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
fhem("set USV_Statusregister $status");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]
[[Kategorie:USV]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-10T19:24:27Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Kommunikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-10T19:23:33Z

Xaneu: /* Umsetzung */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Je nach Anforderung können/müssen entsprechend Anpassungen durchgefüht werden.

Da die Komunnikation über die I2C-Schnittstelle des Raspberry Pi's erfolgt, muss ein geeignetes I2C Interface Modul (z.B. RPII2C, FRM oder NetzerI2C) zuvor definiert werden (siehe Commandref).
Nachfolgend wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-10T19:15:26Z

Xaneu: /* Ausblick */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-10T19:06:20Z

Xaneu: /* Ausblick */

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Die hier vorgestellte Lösung ist als Beispiel zu verstehen. Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter und vollständiger zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-10T19:03:56Z

Xaneu:

[[Datei:Piusvplus.jpg|mini|400px|rechts|Unterbrechungsfreie Spannungsversorgung "PIUSV+]]

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Datei:Piusvplus.jpg

2019-06-10T18:58:31Z

Xaneu: Unterbrechungsfreie Spannungsversorgung PIUSV+

== Beschreibung ==
Unterbrechungsfreie Spannungsversorgung PIUSV+

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-10T18:44:07Z

Xaneu:

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung");
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Meldung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

Anmerkung:
Der Inhalt in USV_Meldung bleibt hier so lange stehen, bis dieser durch einen selbst zu realisierenden set-Befehl gelöscht wird.
Dadurch können auch kurze Spannungsunterbrechungen erfasst werden.

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-05T19:46:39Z

Xaneu: /* Umsetzung */

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung")
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen (Abschaltung erfolgt hier nach 21 Sekunden)
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Leistung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-06-05T19:42:13Z

Xaneu: /* Umsetzung */

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In die Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung;

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv_meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv_meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung")
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy

# PI USV+ Strom
define USV_Strom dummy

# PI USV+ Leistung
define USV_Leistung dummy

# PI USV+ Leistung
define USV_Meldung dummy

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-05-31T07:31:43Z

Xaneu: /* Idee */

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit <code>sudo apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In der Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv-meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv-meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv-meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung")
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
attr USV_Netzteilspannung fp_Raspberry 25,460,2,USV Netzteilspannung:
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
attr USV_Akkuspannung fp_Raspberry 75,460,2,USV Akkuspannung:
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy
attr USV_Spannung fp_Raspberry 125,460,2,USV PI-Spannung:

# PI USV+ Strom
define USV_Strom dummy
attr USV_Strom fp_Raspberry 175,460,2,USV PI-Strom:

# PI USV+ Leistung
define USV_Leistung dummy
attr USV_Leistung fp_Raspberry 225,460,2,USV PI-Leistung:

# PI USV+ Leistung
define USV_Meldung dummy
attr USV_Leistung fp_Raspberry 225,460,2,USV Meldung:

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]

Unterbrechungsfreie Spannungsversorgung "PIUSV+" direkt ansteuern

2019-05-30T07:01:17Z

Xaneu: /* Registerbeschreibung (für eigene Erweiterungen) */

== Idee ==

Hier wird der direkte FHEM-Zugriff auf die Unterbrechungsfreien Spannungsversorgung PIUSV+, die früher von CW2 und aktuell über Reichelt vertrieben wird, beschrieben.
Der direkte Zugriff bedeutet, dass die Kommunikation vollständig über die I2C-Schnittstelle erfolgt, wie es die Originalsoftware "piupsmon" auch bewerkstelligt.

Der direkte Zugriff hat folgenden Vorteile:
* Die Originalsoftware "piupsmon", die für den Betrieb der USV vorgesehen ist, wird nicht bzw. nicht mehr benötig (ggf. sollte diese mit sudo <code>apt-get --purge piupsmon</code> deinstalliert werden). Die Originalsoftware, die vom ursprünglichen Hersteller CW2 stammt und nicht mehr supportet wird, arbeitet nicht immer zuverlässig.
* Es muss kein zusätzliches Skript in die piupsmon-Software zum sauberen Runterfahren des FHEM-Servers eingebunden werden.
* Die direkte Ansteuerung bietet mehr Möglichkeiten (auch für eigene Erweiterungen). So wird beispielsweise nach einem Spannungsausfall wie hier beschrieben der Shutdown nicht nach einer festen Zeit ausgelöst, sondern beim Unterschreiten einer bestimmten Akkusspannung.
* Es können diverse Werte wie Versorgungspannung, Pi-Spannung, Pi-Strom, Pi-Leistung und Akku-Status ausgelesen bzw. angezeigt werden.
* Durch die eigene Kontrolle über die USV wird die Sicherheit erhöht, wodurch ein Crash des Betriebssystems auf dem Systemspeicher (SD-Karte oder externer USB-Speicher) noch effektiv verhindert werden kann.

== Umsetzung ==

I2C-Daten werden über ein I2C Interface Modul wie beispielsweise RPII2C, FRM oder NetzerI2C gesendet. Daher muss eines dieser Module zuvor definiert werden (siehe Commandref).
Hier wurde der Zugriff auf die I2C-Schnittstelle über das Modul RPII2C realisiert.

In der Datei "99_myUtils.pm" müssen die folgende Funktionen kopiert werden:

<syntaxhighlight lang=pl>
sub USV_Werte_auslesen($$)
{
my ($USV_Netzteilspannung_Error_Counter, $USV_Akkuspannung_Error_Counter) = @_;

my $content;
my $u_akku_high;
my $u_akku_low;
my $u_akku;
my $u_netz_high;
my $u_netz_low;
my $u_netz;
my $u_pi_high;
my $u_pi_low;
my $u_pi;
my $i_pi_high;
my $i_pi_low;
my $i_pi;
my $p_pi;
my $usv_meldung

# Werte lesen
fhem("set PIi2c_1 writeByte 18 02");

$content=fhem("get PIi2c_1 readblock 18 10",1);
$content=~ m/received : (\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+).(\d+) |/is;
$u_akku_high=$1;
$u_akku_low=$2;
$u_netz_high=$7;
$u_netz_low=$8;
$u_pi_high=$5;
$u_pi_low=$6;
$i_pi_high=$3;
$i_pi_low=$4;

$u_akku=((($u_akku_high & 0x7F)*256+$u_akku_low)/1000);
$u_netz=((($u_netz_high & 0x7F)*256+$u_netz_low)/1000);
$u_pi=((($u_pi_high & 0x3F)*256+$u_pi_low)/1000);
$i_pi=((($i_pi_high & 0x3F)*256+$i_pi_low)/1000);
$p_pi=floor($u_pi*$i_pi*1000+0.5)/1000;

if ($u_akku<5 && $u_akku>2.5 && $u_netz<6 && $u_pi<6 && $i_pi<3 && not($u_pi==0 && $i_pi>0) && not($i_pi==0 && $u_pi>0))
{
if ($u_netz<0.1)
{
$USV_Netzteilspannung_Error_Counter++;
if ($USV_Netzteilspannung_Error_Counter==2) { $usv-meldung="FHEM: USV-Netzspannung fehlt!"; }
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}
else
{
$USV_Netzteilspannung_Error_Counter=0;
fhem("set USV_Netzteilspannung_Error_Counter $USV_Netzteilspannung_Error_Counter");
}

if ($u_akku<3.0)
{
$USV_Akkuspannung_Error_Counter++;
if ($USV_Akkuspannung_Error_Counter==2) { $usv-meldung="FHEM: USV-Akkuspannung zu niedrig!"; }
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}
else
{
$USV_Akkuspannung_Error_Counter=0;
fhem("set USV_Akkuspannung_Error_Counter $USV_Akkuspannung_Error_Counter");
}

if (($u_netz<0.1) && ($u_akku>3.0) && ($u_akku<3.5)) # shutdown-Bedingung ermitteln
{
$usv-meldung="Raspberry Pi und USV wurden wegen Stromausfall abgeschaltet!";
USV_abschalten();
rasp_shutdown();
}

$u_akku=$u_akku." V (3.0 ... 4.2 V)";
$u_netz=$u_netz." V (5V)";
$u_pi=$u_pi." V (5V)";
$i_pi=$i_pi." A";
$p_pi=$p_pi." W";
fhem("set USV_Datagramm $content");
fhem("set USV_Akkuspannung $u_akku");
fhem("set USV_Netzteilspannung $u_netz");
fhem("set USV_Spannung $u_pi");
fhem("set USV_Strom $i_pi");
fhem("set USV_Leistung $p_pi");
fhem("set USV_Meldung $usv_meldung")
}
}

sub USV_abschalten()
{
# USV-Abschaltung auslösen
fhem("set PIi2c_1 writeByte 18 10");
fhem("set PIi2c_1 writeByte 18 15");
}

sub rasp_shutdown()
{
my @processes = `sudo shutdown -h now`;
}
</syntaxhighlight>

Anmerkung:
Um den Raspberry wie hier direkt vom FHEM aus über den Befehl "sudo shutdown -h now" auszuschalten, muss in die Datei <code>/etc/sudoers.d/010_pi-nopasswd</code> hinter dem Eintrag

<pre>
pi ALL=(ALL) NOPASSWD: ALL
</pre>

folgendes ergänzt werden

<pre>
pi ALL=(ALL) NOPASSWD: ALL
fhem ALL=(ALL) NOPASSWD: /sbin/reboot, /sbin/shutdown, /sbin/halt
</pre>

In der Datei "fhem.cfg" kann dann die Anzeige der USV-Parameter und die Abschaltung der USV beispielsweise folgendermaßen realisiert werden:

<pre>
#i2C-Schnittstelle einrichten
define PIi2c_1 RPII2C 1

# PI USV+ Netzteilspannung
define USV_Netzteilspannung dummy
attr USV_Netzteilspannung fp_Raspberry 25,460,2,USV Netzteilspannung:
define USV_Netzteilspannung_Error_Counter dummy
define USV_Netzteilspannung_Error_Counter_Init notify global:INITIALIZED set USV_Netzteilspannung_Error_Counter 0

# PI USV+ Akkuspannung
define USV_Akkuspannung dummy
attr USV_Akkuspannung fp_Raspberry 75,460,2,USV Akkuspannung:
define USV_Akkuspannung_Error_Counter dummy
define USV_Akkuspannung_Error_Counter_Init notify global:INITIALIZED set USV_Akkuspannung_Error_Counter 0

# PI USV+ Spannung
define USV_Spannung dummy
attr USV_Spannung fp_Raspberry 125,460,2,USV PI-Spannung:

# PI USV+ Strom
define USV_Strom dummy
attr USV_Strom fp_Raspberry 175,460,2,USV PI-Strom:

# PI USV+ Leistung
define USV_Leistung dummy
attr USV_Leistung fp_Raspberry 225,460,2,USV PI-Leistung:

# PI USV+ Leistung
define USV_Meldung dummy
attr USV_Leistung fp_Raspberry 225,460,2,USV Meldung:

# PI USV+ Werte aktualisieren und ggf. Abschaltung auslösen
define USV_Werte_auslesen at +*00:00:05 { USV_Werte_auslesen(Value("USV_Netzteilspannung_Error_Counter"),Value("USV_Akkuspannung_Error_Counter")) }
</pre>

== Registerbeschreibung (für eigene Erweiterungen) ==

Die PIUSV+ kann per I2C-Schnittstelle über die Adresse "0x18" angesprochen werden. 
Achtung: lt. Foren wurde bei älteren PIUSV+ teilweise auch die Adresse "0x30" verwendet. 
Das nächste Byte, das hinter der Adresse an die PIUSV+ gesendet werden muss, ist als Befehl zu verstehen.

Folgende Befehle sind möglich:

<pre>
"Status lesen" 0x00 danach muss 1 Byte (Statusregister) gelesen werden
Die einzelnen Bits des Statusregister haben folgende Bedeutung:
Bit0: Primäre Spannungsversorgung (5V) aktiv
Bit1: Sekundäre Spannungsversorgung (5V...25V) aktiv
Bit2: Akkuspannung zu niedrig
Bit3: Akku wird geladen
Bit4: Akku ist voll
Bit5: Taster S1 an der USV betätigt

"Firmare Version lesen" 0x01 danach müssen 12 Bytes (Zeichen) gelesen werden

"Werte lesen" 0x02 danach müssen 10 Byte gelesen werden
Die zu lesenden Bytes haben folgende Reihenfolge und Bedeutung:
HIGH_BYTE (UINT) Akku-Spannung in mV
LOW_BYTE (UINT) Akku-Spannung in mV
HIGH_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
LOW_BYTE (UINT) Strom in mA, der zum Raspberry Pi fließt
HIGH_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
LOW_BYTE (UINT) 5V-Versorgungsspannung in mV (USV-Spannungversorung für Raspberry Pi)
HIGH_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV am Micro USB-Stecker der USV (primäre Spannungsversorgung)
HIGH_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)
LOW_BYTE (UINT) Spannung in mV externe Spannungsversorgung (sekundäre Spannungsversorgung)

"USV-Abschaltung auslösen" 0x10 danach muss 1 Byte geschrieben werden
Folgende Werte sind möglich:
0x00 (default Wert): USV wird nach einer Zeit von 30sec. abgeschaltet
0x01...0xFF: USV wird nach einer Zeit von 1...255 Sekunden abgeschaltet
Anmerkung: Durch das zeitverzögerte Auschalten der USV kann sichergestellt werden,
dass ein zuvor ausgelöster Shutdown des Raspberry Pi abgeschlossen ist.
</pre>

== Ausblick ==
Es wäre sinnvoll, das hier Beschriebene in einem eigenen Modul z.B. "52_I2C_PIUPS_PLUS.pm" unterzubringen, um den Zugriff noch eleganter zu realisieren. 
 
[[Kategorie:Examples]]
[[Kategorie:Code Snippets]]