|
|
| (59 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt) |
| Zeile 1: |
Zeile 1: |
| Die Speicherung von Perl-Code unmittelbar in [[Eventhandler|Eventhandlern]], [[Timehandler|Timehandlern]] oder anderen Geräten in der [[Konfiguration]], in denen Perl-Ausdrücke angegeben werden können, wird mit wachsender Zahl von Geräten und Logiken eventuell unübersichtlich. Um z.B. Doppelungen zu vermeiden und Logikbausteine zentral vorzuhalten, kann man eine oder mehrere eigene Programmdateien erzeugen, in der diese als kleine Programme gesammelt und dann aus entsprechenden Geräten aufgerufen werden können.
| |
| == Eine neue Programmdatei erzeugen ==
| |
| FHEM enthält eine Vorlage ''myUtilsTemplate.pm'', die zur Erzeugung von Programmdateien genutzt werden sollte; nachfolgend soll beispielhaft eine Datei namens ''99_myUtils.pm'' verwendet werden.
| |
| Vorgehensweise:
| |
| * FHEM-Menüpunkt {{Taste|Edit files}} anklicken
| |
| * Weblink ''myUtilsTemplate.pm'' anklicken
| |
| * Im Textfeld hinter ''Save as'' den Dateinamen ''99_myUtils.pm'' für die Programmdatei eintragen
| |
| : Hinweis: Wenn ein anderer Dateiname angegeben wird, muss der Name Initialize-Routine entsprechend angepasst werden (siehe nachfolgende Erläuterung zur Grundstruktur unter Nr. 3)
| |
| * {{Taste|Save as}} anklicken
| |
| Nun ist die eigene Programmdatei ''99_myUtils.pm'' mit der notwendigen Grundstruktur unter dem Menüpunkt ''Edit files'' zur Bearbeitung mit dem [[codemirror|Integrierter Editor]] zu finden. Für eine einfache und fehlerminimierende Bearbeitung sollten die [[Konfiguration#Syntaxhervorhebung|Syntaxhervorhebungs-, Befehlsauswahl- und Befehlsvervollständigungsfunktionen]] im Integrierten Editor eingeschaltet sein.
| |
|
| |
|
| {{Randnotiz|RNTyp=g|RNText=Nutzt man {{Link2CmdRef|Lang=en|Anker=configDB|Label=configDB}}, können (bzw. sollten) die eigenen Programmdateien in die Datenbank importiert werden, statt unmittelbar im Dateisystem gespeichert zu bleiben. Sie können dann weiter über {{Taste|Edit files}} bearbeitet werden, stehen dann aber z.B. bei einem Umzug oder Neuaufsetzen des Systems direkt wieder zur Verfügung.}}
| |
| Die Programmdateien können zwar auch mit einem [[Konfiguration#Externer Editor|externen Editor]] bearbeitet werden, diese Vorgehensweise wird jedoch nicht empfohlen, da dies insbesondere Einsteigern das debugging erschwert.
| |
|
| |
| Eine ‚leere‘ Programmdatei muss grundsätzlich folgenden Grundstruktur besitzen:
| |
|
| |
| <source lang="perl">
| |
| package main;
| |
| use strict;
| |
| use warnings;
| |
| use POSIX;
| |
| sub
| |
| myUtils_Initialize($$)
| |
| {
| |
| my ($hash) = @_;
| |
| }
| |
| 1;
| |
| </source>
| |
|
| |
| Folgende Dinge sind für eigene Programmdateien besonders zu beachten:
| |
|
| |
| # Der Dateiname muss mit 99_ beginnen. FHEM lädt beim Start alle Programmdateien mit dem prefix 99_. Andere Programmdateien werden erst dann geladen, wenn sie durch eine define-Anweisung in der [[Konfiguration]] angefordert werden. So wird z.B. 10_FS20.pm erst geladen, wenn beim Einlesen der Konfiguration das erste define für ein FS20-device abgearbeitet wird. Da Ihre eigene Programmsammlung wahrscheinlich kein neues Gerät mit einem zugehörigen define-Befehl implementiert, würde sie also nie geladen, wenn ihr Name nicht mit 99_ beginnt.
| |
| # Damit die neue Datei bei ''Edit files'' angezeigt wird, muss sie mit ''Utils.pm'' enden. Also zum Beispiel ''99_meineUtils.pm'' oder ''99_myUtils_Homematic.pm''.
| |
| # Der Name der Programmdatei muss mit dem Namen der Initialize-Routine übereinstimmen. Wenn Sie Ihr Programm also 99_Werkzeugkasten.pm nennen, muss die im code dargestellte initialize-Routine sub Werkzeugkasten_Initialize heißen.
| |
| # Die Zeile <code> 1; </code> muss immer die letzte Programmzeile sein. Wenn Sie also eigene Routinen in Ihre Programmsammlung einfügen, tragen Sie diese zwischen dem Ende der Initialize-Routine und der abschließenden Zeile <code> 1; </code> ein.
| |
|
| |
| == Eigene Routinen einfügen ==
| |
| Als Beispiel dient das Umsetzen von FS20 toggle-Events aus dem Artikel "[[FS20 Toggle Events auf On/Off umsetzen]]".
| |
| Das gesamte Programm sieht dann folgendermaßen aus:
| |
|
| |
| <source lang="perl">
| |
| package main;
| |
| use strict;
| |
| use warnings;
| |
| use POSIX;
| |
| sub
| |
| myUtils_Initialize($$)
| |
| {
| |
| my ($hash) = @_;
| |
| }
| |
| ##########################################################
| |
| # Untoggle
| |
| # toggle-Vorgänge in den Status on/off umsetzen
| |
| sub Untoggle($) {
| |
| my ($obj) = @_;
| |
|
| |
| if( Value($obj) eq "toggle" ){
| |
| if( OldValue($obj) eq "off" ) {
| |
| fhem( "setstate $obj on" );
| |
| }
| |
| else {
| |
| fhem( "setstate $obj off" );
| |
| }
| |
| }
| |
| else {
| |
| fhem( "setstate $obj ".Value($obj) );
| |
| }
| |
| }
| |
| 1;</source>
| |
| Der Aufruf erfolgt dann z.B. so:
| |
|
| |
| <pre>#fhem.cfg
| |
| define lampe_untoggle notify lampe {Untoggle("$NAME")}</pre>
| |
| Der Aufruf aus einem notify (oder at) erfolgt als Perl-code, muss also in geschweiften Klammern stehen. Der Aufruf erfolgt durch Angabe des Namens der Routine (Untoggle) unter Angabe der zu übergebenden Parameter (hier "$NAME").
| |
| Im Programm wurde die Routine Untoggle mit '''einem''' Parameter definiert ( Untoggle($) , die Anzahl der $-Zeichen bestimmt die Anzahl der zu übergebenden Parameter). Der Wert des übergebenen Parameters wird in der ersten Programmzeile in die Variable $obj übernommen (my ($obj) = @_; ).
| |
| Der Aufruf erfolgt mit Untoggle(„$NAME“) . Der Platzhalter $NAME in fhem steht für den Namen des Geräts. Im o.g. Beispiel erfolgt der Aufruf also eigentlich mit Untoggle(„lampe“). Natürlich können beim Aufruf auch feste Werte ( „lampe1“ ) oder Variablen ( $hour ) übergeben werden.
| |
|
| |
| === Routinen mit mehreren Parametern ===
| |
| In der Definition der Routine geben Sie außerdem an, wieviele Parameter übergeben werden sollen, für 2 Parameter z.B. so:
| |
|
| |
| <source lang="perl">define test at *09:00 { wakeup($we, "Schlafzimmerlampe") }</source>
| |
| Die Deklaration der Routine in Ihrer Programmdatei muss dann so beginnen:
| |
|
| |
| <source lang="perl">#Nur am Wochenende eingeschaltet
| |
| sub wakeup($$) {
| |
| my ($wochenende, $device) = @_;
| |
| if ($wochenende) {
| |
| fhem( "set $device on" );
| |
| }
| |
| else {
| |
| fhem( "set $device off" );
| |
| }
| |
| }</source>
| |
| Durch die Anzahl der $-Zeichen in der Routinen-Deklaration wird also die Anzahl der Parameter festgelegt. In der ersten Programmzeile Ihrer Routine übernehmen Sie dann die übergebenen Parameterwerte in lokale Variablen. Wie beim Routinen-Aufruf muss auch hierbei die Anzahl der Parameter mit der Routinen-Deklaration (also Anzahl der $-Zeichen) übereinstimmen<ref>Mehr zu diesen sog. prototypes ist z.B. [https://perldoc.perl.org/perlsub.html#Prototypes hier] nachzulesen; auch [[fhem.pl]] beginnt mit einer Liste der prototyes der darin enthaltenen Funktionen. Da diese Funktionen auch innerhalb der myUtils verwendet werden können, empfiehlt es sich, zunächst dort nachzusehen, ob eventuell bereits hilfreiche Funktionen für das zu lösende Problem vorhanden sind.</ref>.
| |
|
| |
| === Routinen ohne Parameter ===
| |
| Auch Routinen ohne Parameter sind natürlich möglich. Definition und Aufruf sehen dann folgendermassen aus:
| |
|
| |
| <source lang="perl">sub parameterlos() {
| |
| ...
| |
| }</source>
| |
| { parameterlos() }
| |
|
| |
| == Eigene Programmdatei laden ==
| |
| Die Programmdatei wird beim FHEM-Start immer automatisch geladen.
| |
|
| |
| Bei Änderungen an der Programmdatei bei laufendem FHEM ist bezüglich Neuladen ohne FHEM-Neustart zwischen den verschiedenen Bearbeitungsvarianten der Progammdatei zu unterscheiden.
| |
|
| |
| Bei der Bearbeitung über den '''Integrierten Editor''' wird die Programmdatei beim Abspeichern automatisch mit den Änderungen neu geladen.
| |
|
| |
| Bei der nicht empfohlenen Bearbeitung der Programmdatei mit einem '''externen Editor''' muss FHEM manuell angewiesen werden, die Programmdatei mit den Änderungen zu laden. Also bearbeiten Sie Ihr Programm, speichern die Programmdatei, und weisen FHEM dann explizit an, die Programmdatei erneut zu laden. Der Befehl dazu, der in das Befehls-Eingabefeld eingegeben wird, lautet: <code>reload 99_myUtils.pm</code>
| |
|
| |
| Treten beim Laden (Syntax)fehler auf, werden diese am Bildschirm wie auch im Log angezeigt. Da der Ladevorgang fehlgeschlagen ist, stehen Ihre eigenen Routinen nun nicht zur Verfügung (bzw. in der zuletzt erfolgreich geladenen Version). Es empfiehlt sich daher bei der Entwicklung neuer Code-Teile v.a. für "Einsteiger", diese zunächst in einer separaten myUtils-Datei zu entwickeln und erst dann in die für den "produktiven Betrieb" genutzten myUtils-Dateien zu übernehmen, wenn sie als funktional getestet anzusehen sind.
| |
| == Eigene Programmdatei dokumentieren ==
| |
| In der lokalen Commandref kann man die eigenen Routinen auch dokumentieren.
| |
| Dazu muss am Ende der 99_myUtils folgender Codeblock eingefügt werden
| |
| <source lang="perl">
| |
| =pod
| |
| =begin html
| |
|
| |
| <a name="myUtils"></a>
| |
| <h3>myUtils</h3>
| |
| <ul>
| |
| <b>Name</b>
| |
| <br>
| |
| Text<br>
| |
| Examples:
| |
| <ul>
| |
| <code>Example Code </code><br>
| |
| </ul>
| |
| </ul>
| |
|
| |
| =end html
| |
| =begin html_DE
| |
|
| |
| <a name="myUtils"></a>
| |
| <h3>myUtils</h3>
| |
|
| |
| =end html_DE
| |
| =cut
| |
| </source>
| |
|
| |
| Der a Tag stellt einen Verweis dar, der h3 Tag kennzeichnet die Überschrift. Beide Tags müssen sein, ansonsten kann FHEM die Doku nicht in die commandref einbinden. Der Abschnitt für die deutsche Doku kann komplett fehlen. Die Beschreibungen der einzelnen Routinen werden mit ul Tags geklammert und eventuell mit ul Tags weiter untergliedert. Dabei entsteht ein eingerückter Text. Beispiele können mit dem code Tag formatiert werden.
| |
|
| |
| Mit diesem Befehl kann die Erzeugung des Commandrefeintrages initiiert und getestet werden:
| |
| <source lang="perl">{system("/usr/bin/perl ./contrib/commandref_join.pl")}</source>
| |
| Für eine schnelle Überprüfung des Commandrefeintrages können Sie auch <source lang="perl">help myUtils</source> (bzw. statt myUtils den Namen Ihrer Utils-Datei) eingeben.
| |
|
| |
| == Weitere Informationen ==
| |
| Weiterführende Hinweise, z.B. wie aus einer Sammlung kleiner Tools ggf. ein eigenes Modul entstehen kann, sind der [[DevelopmentModuleIntro]] zu entnehmen. Dort sind v.a. auch einige häufig benötigte Funktionen aus fhem.pl dokumentiert.
| |
|
| |
| == Links ==
| |
| * Eine Zusammenstellung wichtiger Funktionen ist in den Perl specials der {{Link2CmdRef|Anker=perl|Label=commandref}} enthalten.
| |
| * Eine weitere Sammlung hilfreicher "Helferlein" samt Hilfe enthält 99_Utils.pm.
| |
| * Hilfsfunktionen für Farboperationen: [[Color]].
| |
| * [[Zeitangaben, rechnen mit|Wiki-Beitrag zum Rechnen mit Zeitangaben]]
| |
| * [[Gleitende Mittelwerte berechnen und loggen]]
| |
| * Beispiele für Geräteüberwachungen: [[EBUS#Mithilfe von FHEM|EBUS]], [[Netzwerkgeräte:_Verfügbarkeit_prüfen#Erweiterung 99 myUtils|Netzwerkgeräte]], {{Link2Forum|Topic=51267|Message=935071|LinkText=Nextion-Display bei Inaktivität zurücksetzen}}, {{Link2Forum|Topic=97173|Message=917347|LinkText=devStateIcon für das Modul ''monitoring''}}
| |
| * [[Batterieüberwachung#Alternativ per Skript|Batterieüberwachung]]
| |
| * Routine zum [[E-Mail_senden#Raspberry Pi|E-Mail senden]] aus FHEM heraus
| |
| * [[E-Mail per notify nach Zeitablauf erneut senden|Beispiel]], wie ggf. an mehreren Stellen relevante Variablen zentral zur Verfügung gestellt werden können.
| |
| * [[Plot-Abriss_vermeiden#Implementierung|Plot-Abrisse vermeiden]]
| |
| * Formatierungsanweisungen auslagern: [[ReadingsGroup#Enigma_Receiver|ReadingsGroup]], [[Spritpreismonitor#Farbliche_Hervorhebung|Spritpreismonitor]], [[EBUS-MQTT2#myUtils-Code|Balkenanzeige]] (hier: für EBUS)
| |
| * Befehle an ein Netzwerkgerät senden: [[Listenlive#Der Code|Listenlive]]
| |
| * [[HM-Dis-WM55_Funk_Statusanzeige#99_myUtils|Homematic-Display]] mit Informationen versorgen
| |
| * {{Link2Forum|Topic=34363|Message=266811|LinkText=Zeit- und Datumsvariablen $hour, $wday, $month, ... in 99_myUtils.pm verfügbar machen}}
| |
| * {{Link2Forum|Topic=36504|Message=287778|LinkText=Globale und flexible Fenster- und Türüberwachung}}
| |
| * {{Link2Forum|Topic=87895|Message=803439|LinkText=57_CALENDAR.pm - events mit deviceNames nutzen}}
| |
| * {{Link2Forum|Topic=96959|Message=901268|LinkText=Konstanten für das Rechnen mit Zeiten}}
| |
| * {{Link2Forum|Topic=97430|Message=906576|LinkText=devStateIcon-Code für Homematic-Thermostate}}
| |
| * {{Link2Forum|Topic=86073|Message=836537|LinkText=php-Script aufrufen und Rückgabewert in einen dummy schreiben}} (hier: Viessmann Heizung))
| |
| * {{Link2Forum|Topic=84831|Message=771485|LinkText=Windchill und Hitzeindex berechnen}}
| |
| * {{Link2Forum|Topic=84016|Message=762888|LinkText=Countdown Timer}}
| |
|
| |
|
| |
| <references />
| |
| [[Kategorie:Code Snippets]]
| |
| [[Kategorie:HOWTOS]]
| |
