FHEMWiki - Benutzerbeiträge [de]

Volkszaehler

2021-11-05T18:47:51Z

ChristophMorrison: /* Daten mit Volkszaehler loggen */ Hinweis darauf, dass 23_VOLKSZAEHLER geladen sein muss, da sonst LWP::UserAgent::get nicht verfügbar ist (Forum #123917)

{{Infobox Modul
|ModPurpose=Einbindung der Daten von voelkszaehler.org in FHEM
|ModType=x
|ModCmdRef=VOLKSZAEHLER
|ModForumArea=
|ModFTopic=http://forum.fhem.de/index.php/topic,12834.0.html
|ModTechName=23_VOLKSZAEHLER.pm
|ModOwner=({{Link2FU|81|Forum}}/[[Benutzer Diskussion:Bgewehr|Wiki]])
}}
[[Datei:volkszaehler.png|right]]

Volkszaehler.org ist ein freies SmartMeter Projekt für den Selbstbau ([http://www.volkszaehler.org siehe volkszaehler.org]) Der Nutzer behält dabei die vollständige Kontrolle über die anfallenden Daten seiner Strom-, Wasser- und Gaszähler.

==Features==
* 100% Open-Source
* kostenlos
* offene Protokolle
* erweiterbar
* minmale Anforderungen (LAMP-Stack)
* flexibele Verwaltungsmöglichkeiten
* Verbrauchs & Kostenprognose
* verschiedenste Messgrößen
** Strom
** Wasser
** Gas
** Betriebsstunden
** Temperatur
* Läuft u. a. auf Raspberry Pi ([http://wiki.volkszaehler.org/howto/raspberry_pi_image Installationsbeschreibung)]

== Volkszaehler in FHEM einbinden ==

Das FHEM-Modul für Volkszaehler.org bindet diese Daten in FHEM ein. Das Modul 23_VOLKSZAEHLER.pm greift per http auf den Volkszaehler zu und interpretiert die JSON-Antwort in FHEM-device-Readings. Daraus können Logs und Plots gebildet werden oder devices mit Kennzahlen aus den Volkszaehler-Daten.

Es ist z. B. für Solarstrom-Anlagenbesitzer denkbar, bei hoher verfügbarer Sonnenenergie mit FHEM Verbraucher einzuschalten, um die Eigenverbrauchsrate zu erhöhen, was die Energiekosten reduziert.

== Installation ==
Für die Installation müssen einige Files heruntergeladen und in die richtigen Verzeichnisse kopiert werden.

=== FHEM-Modul ===

Meine aktuellen Versionen liegen hier: <code>https://github.com/bgewehr/fhem</code>

Die Datei <code>23_VOLKSZAEHLER.pm</code> kommt ins Verzeichnis <code>../fhem/FHEM</code>

Die Datei <code>volkszaehler.gplot</code> kommt ins Verzeichnis <code>../fhem/www/gplot</code>

Nur zur Sicherheit: Um die Dateien auf einem Windows-Rechner lokal zu erstellen, bitte den Text aus der "raw" Ansicht aus Github kopieren und bitte nicht in Notepad, sondern in z. B. [http://www.heise.de/download/notepad.html Notepad++] einfügen und dann unter dem richtigen Dateinamen speichern. Mit Notepad von Microsoft werden falsche Zeilenenden erzeugt, die dann unter Linux nicht funktionieren.

=== JSON für Perl ===
Das Modul nutzt einen JSON-Interpreter, um die Antwort vom Volkszaehler in eine PERL-Variable zu wandeln. Dazu ist ein zusätzliches PERL Modul notwendig.

#> cpan JSON

sollte alle nötigen Dateien installieren.

Hinweis zur Fritz!Box:
Da die Fritz!Box inzwischen nicht mehr für FHEM taugt, habe ich die für diese Installation nötigen beonderen JSON files hier nicht mehr aufgelistet. Auch die aktuelle Version meines Moduls greift auf das aktuelle JSON Perl Modul zurück und wird so auf einer Fritz!Box nicht mehr laufen.

== Definition der devices ==
Die Device-Definitionen werden in einer [[Konfiguration]] (üblicherweise fhem.cfg) angelegt
:<code>define <name> VOLKSZAEHLER <ip-address> <port-nr> <channel> <state:last/min/max/average/consumption> <poll-delay></code>

* <name>: Name des neuen FHEM-devices
* <ip-address>: IP des Volkszaehlers
* <port-Nr>: Port, auf dem der Volkszaehler-http-Server erreichtbar ist
* <channel>: UUID des Volkszaehler-Frontend-Channels, der gelesen werden soll
* <state>: Das Reading, welches als state genommen werden soll, kann im define gewählt werden. Dabei besteht die Auswahl aus
** last (letzter geladener Wert, manchmal leer bei zu kleinem poll-delay)
** min (kleinster Wert innerhalb des poll-delay, manchmal leer bei zu kleinem poll-delay)
** max (größter Wert innerhalb des poll-delay, manchmal leer bei zu kleinem poll-delay)
** average (Durchschnitt der Werte im poll-delay, manchmal leer bei zu kleinem poll-delay)
** consumption (Verbrauch innerhalb des poll-delays, manchmal leer bei zu kleinem poll-delay)
* <poll-delay>: Zeitraum, der ausgelesen werden soll in Sekunden

== Beispiele ==
Ein vollständiges Beispiel für die erforderlichen Definitionen und das daraus resultierende Ergebnis:

=== Momentanverbrauch ===
Kanal im Volkszaehler, der den Momentanverbrauch per I/R-Lesekopf ermittelt (alle 60 Sekunden, daraus der Mittelwert)

define Verbrauch_aktuell VOLKSZAEHLER 192.168.178.45 80 635481a0-6fcd-11e2-8587-eda25228f8bf average 60
attr Verbrauch_aktuell group Strom
attr Verbrauch_aktuell room Volkszaehler

=== Logdatei ===
Definition der Logdatei, aus der die Grafik erzeugt werden kann:

define FileLog_Verbrauch_aktuell FileLog ./log/Verbrauch_aktuell-%Y-%m.log Verbrauch_aktuell
attr FileLog_Verbrauch_aktuell logtype text
attr Verbrauch_aktuell room Volkszaehler

=== Der Graph dazu ===
define FilePlot_Verbrauch_aktuell weblink fileplot FileLog_Verbrauch_aktuell:Volkszaehler:CURRENT
attr FilePlot_Verbrauch_aktuell label "Stromverbrauch: $data{currval1}"
attr FilePlot_Verbrauch_aktuell room Volkszaehler

=== Zählerstand ===
Kanal im Volkszaehler, der den Zählerstand per I/R-Lesekopf ermittelt, jede Stunde davon der letzte Wert.

define Zaehlerstand VOLKSZAEHLER 192.168.178.45 80 ebb9c9b0-7058-11e2-b5ed-d12ec87a3a7f last 1800
attr Zaehlerstand group Strom
attr Zaehlerstand room Volkszaehler

=== Verbrauch ===
Kanal im Volkszaehler, der den Zählerstand per I/R-Lesekopf ermittelt, alle 24 Stunden davon der Verbrauch.

define Verbrauch_24h VOLKSZAEHLER 192.168.178.45 80 635481a0-6fcd-11e2-8587-eda25228f8bf consumption 86400
attr Verbrauch_24h group Strom
attr Verbrauch_24h room Volkszaehler

=== Ergebnis ===
[[Datei:23_volkszaehler.JPG|mini|zentriert|hochkant=3.0|Strom- und Gasverbrauch aus Volkszählerdaten generiert - Beispieldarstellung]]

== Daten mit Volkszaehler loggen ==
Hier eine Möglichkeit mit einem notify Temperaturen (oder andere Messwerte) an die Middelware vom Volkszaehler zu schicken um die Daten über ein Volkszaehler Frontend auswerten zu können ('''Achtung''': folgender Kode-Schnipsel funktioniert nur, wenn 23_VOLKSZAEHLER installiert und geladen wurde):
<syntaxhighlight lang="Perl">
.*:temperature.* {
# return "Heizung $NAME" if $NAME =~ /\A.{3}Heizung/; # [[MAX]] Geräte ausschließen. Workaround für aufgebrauchte credits.
my $base_url = AttrVal('vz', 'vz_URL', undef);
my $temp = ReadingsVal($NAME, 'temperature', undef);
my $uuid = AttrVal($NAME, 'vz_UUID', undef);
unless (defined($uuid)) {
my $create_url = $base_url . '/channel.json?type=temperature&title=' . $NAME . '&public=on&style=lines&operation=add';
Log 5, $create_url;
my $response = decode_json(get($create_url));
$uuid = $response->{entity}->{uuid};
$attr{$NAME}{'vz_UUID'} = $uuid;
Log 4, "created $uuid for $NAME";
}
my $update_url = $base_url . '/data/' . $uuid . '.json?operation=add&value=' . $temp;
Log 5, $update_url;
Log 4, get($update_url);
}
</syntaxhighlight>

Der Volkszaehler-URL wird in einem Attribut (vz_URL) eines [[dummy|dummies]] gespeichert, welches vorher angelegt werden muss.

Jedes Thermometer, das auch im Volkszaehler erscheinen soll, muss nun nur noch im Volkszaehler angelegt werden und die UUID als Attribut (vz_UUID) des Thermometers gespeichert werden. Dieser Schritt kann auch ausgelassen werden. In diesem Fall wird ein neues Thermometer automatisch angelegt.

define vz dummy
attr vz vz_URL http://localhost/volkszaehler.org/htdocs/middleware.php
attr vz vz_UUID XXXXXXXXXXXXXXXXXXXXXXXXXXX

== Links ==
* Volkszähler [http://www.volkszaehler.org Homepage]
* [https://github.com/bgewehr/fhem FHEM Module] für Volkszähler von "bgewehr"

[[Kategorie:Other Components]]
[[Kategorie:HOWTOS]]
[[Kategorie:Energieverbrauchsmessung]]

DevelopmentModuleAPI

2021-10-24T19:48:05Z

ChristophMorrison: /* ReadingsNum */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<syntaxhighlight lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===
:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabewert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000

# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight><code>$round</code> wird direkt, d.h. ohne Validierung, in den [https://perldoc.perl.org/functions/sprintf format string] in <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code> übernommen und ausgewertet.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p});
# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f

ReadingsNum(q(foo), q(bar), q(Kein Wert), q(foo));
# = 123oof
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-30T15:24:21Z

ChristophMorrison: /* Fallstricke */ Weiteres Beispiel für Fallstrick hinzugefügt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000

# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight><code>$round</code> wird direkt, d.h. ohne Validierung, in den [https://perldoc.perl.org/functions/sprintf format string] in <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code> übernommen und ausgewertet.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p});
# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f

ReadingsNum(q(foo), q(bar), q(Kein Wert), q(foo));
# = 123oof
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-30T10:49:52Z

ChristophMorrison: /* ReadingsNum */ Hinweis auf Übergaben an $round

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000

# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight><code>$round</code> wird direkt in den [https://perldoc.perl.org/functions/sprintf format string] in <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code> übernommen und ausgewertet.<syntaxhighlight>
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
ReadingsNum(q(foo), q(bar), q(Kein Wert), q{%%p});

# Evaluiert %p zu einer Speicheradresse, z.B. 7fa1fb03d738f
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-30T10:44:23Z

ChristophMorrison: /* ReadingsNum */ Weitere Beispiele hinzugefügt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im strikt mathematischen Sinne, sondern bietet zusätzlich eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = "Kein Wert"

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000

# Device foo, Reading bar, Wert "123 °C"
ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.00000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-30T10:41:10Z

ChristophMorrison: /* ReadingsNum */ Fallstricke hinzugefügt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im mathematischen Sinne, sondern eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.45

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = Kein Wert

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.5

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.45000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

==== Fallstricke ====
Der Rückgabewert muss nicht unbedingt ein numerischer Wert sein, wenn als <code>$default</code> kein numerischer Wert oder <code>undef</code> übergeben wurde. Vergleiche mit numerischen Operatoren werden dann ggf. ein Warning erzeugen.<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.45 °C"

# Lese aus dem Reading baz, nicht bar, wird fehlschlagen
if ( ReadingsNum(q(foo), q(baz), q(Kein Wert), 0) == 123.5 ) {
say q(Wert ist 123.5);
}

# Argument "Kein Wert" isn't numeric in numeric eq (==)
</syntaxhighlight>

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-29T11:52:08Z

ChristophMorrison: /* ReadingsAge */

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im mathematischen Sinne, sondern eine Formatierung.

==== Beispiele ====
<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.42 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.42

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = Kein Wert

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.4

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.42000
</syntaxhighlight>

==== Parameter ====
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

==== Rückgabewert ====
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-29T11:51:08Z

ChristophMorrison: /* ReadingsNum */ Hinweis darauf, dass round() kein mathematisches Runden bietet, sondern eine Formatierung

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt - round ist daher kein round im mathematischen Sinne, sondern eine Formatierung.

Beispiele:<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.42 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.42

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = Kein Wert

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.4

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.42000
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-29T11:35:50Z

ChristophMorrison: /* ReadingsNum */ Beispiele hinzugefügt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>; überzählige Stellen werden mit 0 aufgefüllt.

Beispiele:<syntaxhighlight lang="perl" line="1">
# Device foo, Reading bar, Wert "123.42 °C"

ReadingsNum(q(foo), q(bar), q(Kein Wert));
# = 123.42

ReadingsNum(q(foo), q(baz), q(Kein Wert));
# = Kein Wert

ReadingsNum(q(foo), q(bar), q(Kein Wert), 0);
# = 123

ReadingsNum(q(foo), q(bar), q(Kein Wert), 1);
# = 123.4

ReadingsNum(q(foo), q(bar), q(Kein Wert), 5);
# = 123.42000
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-29T09:37:10Z

ChristophMorrison: /* ReadingsNum */ Klargestellt, welche Teile aus einem Readings extrahiert und wie sie zurückgeliefert werden

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum</code> extrahiert den numerischen Teil des Readings <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück, wenn er existiert. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert oder kein numerischer Teil ermittelt werden konnte.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-29T09:08:14Z

ChristophMorrison: /* ReadingsNum */ Link auf FHEM round() um Missverständnisse zu vermeiden

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum()</code> extrahiert einen numerischen Wert aus dem Reading <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden. Verwendet wird hierzu die FHEM-eigene Funktion <code>[https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm#L239 round]</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$number</code>''' || Numerischer Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

DevelopmentModuleAPI

2021-07-29T09:05:23Z

ChristophMorrison: /* ReadingsNum */ $round Parameter hinzugefügt

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$value = ReadingsNum($name, $reading, $default, $round);
</syntaxhighlight>
Die Funktion <code>ReadingsNum()</code> extrahiert einen numerischen Wert aus dem Reading <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben. Es ist möglich, den Rückgabe wert durch Angabe von <code>$round</code> auf <code>$round</code> Stellen zu runden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|-
|'''<code>$round</code>'''
''optional''
|Der ermittelte Wert, ob Standard oder aus einem Reading, wird auf ''$round'' Anzahl Stellen gerundet.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$number</code>''' || Numerischer Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

FHEMWEB/Widgets

2021-04-28T13:56:40Z

ChristophMorrison: Typos gefixt

Widgets sind Frontendelemente, die der Dateneingabe und -anzeige dienen. Die hier gezeigten Frontendelemente werden durch [[FHEMWEB]] ([[PGM2]]) bereitgestellt.

== Syntax ==
Die Syntax der Widgets ist unter dem Attribut [https://fhem.de/commandref_DE.html#widgetOverride widgetOverride] in der Befehlreferenz beschrieben.

== Verwendung ==
Viele Module (u.a. [[DOIF]], [[dummy]], [[MQTT_DEVICE]], [[MQTT2_DEVICE]], [[MYSENSORS_DEVICE]], [[readingsGroup]]) bieten die Möglichkeit eine Benutzerschnittstelle zu erstellen.

Widgets werden über <code><name>:<modifier></code>-Paare an [[Readings]] oder [[Attribute]] gebunden, dabei ist:

* <code><name></code> ein Readingsname, ein Attribut oder ein Mapping-Argument.
* <code><modifier></code> ein Widget einschliesslich Parameter.

Bei der Erstellung spielen verschiedene Attribute zusammen:

* Mit [[readingList]] (bzw. bei Modulen, die dies nicht kennen: widgetOverride) ist es möglich den Set-Befehl auf [[Readings]] zu erweitern, s. [https://fhem.de/commandref_DE.html#readingList readingList].
* Mit [[setList]] (bzw. widgetOverride) werden die Widgets einem Reading zugeordnet und parametrisiert, s. [https://fhem.de/commandref_DE.html#setList setList].
* Mit [[webCmd]] werden die Widgets angezeigt, s. [https://fhem.de/commandref_DE.html#setList webCmd].
* Mit [[webCmdLabel]] werden die Widgets beschriftet und tabellarisch angeordnet, s. [https://fhem.de/commandref_DE.html#webCmdLabel webCmdLabel].
* Mit [[widgetOverride]] ist es möglich, die im Modul festgelegten Widgets zu überschreiben, s. [https://fhem.de/commandref_DE.html#widgetOverride widgetOverride].
* Mit [[eventMap]] ist es möglich Widgets an Mapping-Argumente zu binden, s. [https://fhem.de/commandref_DE.html#eventMap eventMap] und {{Link2Forum|Topic=76755|LinkText=eventMap und Widget-Anbindung}} .
Das Zusammenspiel dieser Attribute ist u.A. im Artikel [[DeviceOverview anpassen#webCmd .26 Co|DeviceOverview anpassen]] näher erläutert.

== Zusammenstellung der Widgets ==

Die Bildschirmkopie zeigt das Benutzerinterface des Dummys mit den Widgets
[[Datei:fhemweb_widgets.png]]

=== weitere Konfiguration ===

* '''knob''', siehe http://anthonyterrien.com/knob/
* '''colorpicker''', siehe [[Color]]

== Das Beispiel für [[DOIF/Import_von_Code_Snippets|Raw definition]] zum Ausprobieren ==

In der vorstehenden Abbildung fehlt das Look and Feel der Widgets. Mit dem folgenden Code-Snippet zum Ausprobieren, wird dies ergänzt.

<pre>
defmod widgets dummy
attr widgets readingList 00select 01select 02selectnumbers 03selectnumbers 04textField 05textFieldNL 06textField-long 07textFieldNL-long 08slider 09multiple 10multiple-strict 11knob 12sortable 13sortable-strict 14sortable-given 15uzsuToggle 16uzsuSelect 17uzsuSelectRadio 18uzsuDropDown 19colorpicker_RGB 19colorpicker_HSV 19colorpicker_CT 19colorpicker_HUE 19colorpicker_BRI 20time 21iconRadio 21iconRadio_use4icon 22iconSwitch 23iconLabel 24iconButtons 24iconButtons_use4icon 25bitfield
attr widgets room 1_Widgets
attr widgets setList 00select:1,2,3,4,5,a,b,c,def,hik \
01select:select,1,2,3,4,5,a,b,c,def,hik \
02selectnumbers:selectnumbers,7,0.5,30,1,lin \
03selectnumbers:selectnumbers,1,0.0625,140000,0,log10 \
04textField:textField \
05textFieldNL:textFieldNL\
06textField-long:textField-long \
07textFieldNL-long:textFieldNL-long \
08slider:slider,7,0.5,30,1 \
09multiple:multiple,shirt,shoes,skirt,trowsers \
10multiple-strict:multiple-strict,red,green,blue,yellow \
11knob:knob,min:0,max:360,width:50,height:50,step:1,lineCap:round,angleOffset:180,cursor:3,thickness:.3 \
12sortable:sortable,blue,shirt,white,shoes,brown,skirt,black,jeans\
13sortable-strict:sortable-strict,blue,shirt,white,shoes,brown,skirt,black,jeans\
14sortable-given:sortable-given,blue,shirt,white,shoes,brown,skirt,black,jeans\
15uzsuToggle:uzsuToggle,ON,OFF\
16uzsuSelect:uzsuSelect,blue,shirt,white,shoes,brown,skirt,black,jeans\
17uzsuSelectRadio:uzsuSelectRadio,MW,KW,UKW\
18uzsuDropDown:uzsuDropDown,red,green,blue,yellow \
19colorpicker_RGB:colorpicker,RGB \
19colorpicker_HSV:colorpicker,HSV \
19colorpicker_CT:colorpicker,CT,2000,10,6500 \
19colorpicker_HUE:colorpicker,HUE,0,1,359 \
19colorpicker_BRI:colorpicker,BRI,0,1,100 \
20time:time \
21iconRadio:iconRadio,#808080,10,fts_shutter_10@FFA500,20,fts_shutter_20@orange,30,fts_shutter_30@orange,40,fts_shutter_40@orange,50,fts_shutter_50@orange,60,fts_shutter_60@orange,70,fts_shutter_70@orange,80,fts_shutter_80@orange,90,fts_shutter_90@orange,100,fts_shutter_100@orange \
21iconRadio_use4icon:iconRadio,use4icon@808080,10,fts_shutter_10@FFA500,20,fts_shutter_20@orange,30,fts_shutter_30@orange,40,fts_shutter_40@orange,50,fts_shutter_50@orange,60,fts_shutter_60@orange,70,fts_shutter_70@orange,80,fts_shutter_80@orange,90,fts_shutter_90@orange,100,fts_shutter_100@orange \
22iconSwitch:iconSwitch,wide#open,@red,half#open,fts_shutter_50@%23cd2906,totally#closed,fts_shutter_100@magenta,half#closed, \
23iconLabel:iconLabel,wide#open,@red,half#open,fts_shutter_50@%23cd2906,totally#closed,fts_shutter_100@magenta,half#closed,\
24iconButtons:iconButtons,orange,Bad,sani_heating@green,Wohnzimmer_1,sani_heating@green,Wohnzimmer_2,sani_heating@green,Esszimmer,sani_heating@green,Diele,sani_heating@green,Gäste_WC,sani_heating@green,Büro,sani_heating@green,Wintergarten,sani_heating@green,Werkstatt,sani_heating@green,Schlafzimmer,sani_heating@green \
24iconButtons_use4icon:iconButtons,use4icon@red,Bad,sani_heating@0000FF,Wohnzimmer_1,sani_heating@blue,Wohnzimmer_2,sani_heating@blue,Esszimmer,sani_heating@blue,Diele,sani_heating@blue,Gäste_WC,sani_heating@blue,Büro,sani_heating@blue,Wintergarten,sani_heating@blue,Werkstatt,sani_heating@blue,Schlafzimmer,sani_heating@0000FF\
25bitfield:bitfield
attr widgets userReadings 23iconLabel:22iconSwitch.* {ReadingsVal($name,"22iconSwitch","wideopen")}
attr widgets webCmd 00select:01select:02selectnumbers:03selectnumbers:04textField:05textFieldNL:06textField-long:07textFieldNL-long:08slider:20time:09multiple:10multiple-strict:11knob:12sortable:13sortable-strict:14sortable-given:15uzsuToggle:16uzsuSelect:17uzsuSelectRadio:18uzsuDropDown:19colorpicker_RGB:19colorpicker_HSV:19colorpicker_CT:19colorpicker_HUE:19colorpicker_BRI:21iconRadio:21iconRadio_use4icon:24iconButtons:24iconButtons_use4icon:22iconSwitch:23iconLabel:25bitfield
attr widgets webCmdLabel select (default)\
:select (explicit)\
:selectnumbers (linear)\
:selectnumbers (logarithmic)\
:textField\
:textFieldNL (no label)\
:textField-long (multi-line)\
:textFieldNL-long (multi-line,no label)\
:slider\
:time\
:multiple\
:multiple-strict\
:knob\
:sortable\
:sortable-strict\
:sortable-given\
:uzsuToggle\
:uzsuSelect\
:uzsuSelectRadio\
:uzsuDropDown\
:colorpicker RGB\
:colorpicker HSV\
:colorpicker Farbtemperatur\
:colorpicker Farbton\
:colorpicker Helligkeit\
:iconRadio\
:iconRadio prefix use4icon\
:iconButtons\
:iconButtons prefix use4icon\
:iconSwitch\
:iconLabel\
:bitfield
attr widgets widgetOverride readingList|setList|webCmd|webCmdLabel:textField-long

setstate widgets iconSwitch wide open
setstate widgets 2017-08-29 20:32:22 00select 1
setstate widgets 2017-08-29 20:43:04 01select 2
setstate widgets 2017-08-24 17:38:22 02selectnumbers 10.5
setstate widgets 2017-08-24 17:38:51 03selectnumbers 64938
setstate widgets 2017-10-06 16:37:24 04textField Hello
setstate widgets 2017-08-24 17:39:22 05textField Hallo
setstate widgets 2017-10-06 16:37:25 05textFieldNL Hello
setstate widgets 2017-08-24 17:57:54 06textField-long Hello
setstate widgets 2017-10-06 16:37:23 07textFieldNL-long Hello
setstate widgets 2017-10-06 16:37:42 08slider 19.5
setstate widgets 2017-08-24 18:22:40 09multiple shirt,shoes
setstate widgets 2017-08-24 18:22:57 10multiple-strict red,green
setstate widgets 2019-07-30 20:08:44 11knob 120
setstate widgets 2017-08-29 08:11:40 12sortable shirt,brown,skirt,white,shoes,black,jeans
setstate widgets 2017-08-24 18:48:17 13sortable-strict blue,white,shirt,shoes,brown,skirt,black,jeans
setstate widgets 2017-08-24 18:49:34 14sortable-given blue,shirt,white,shoes,brown,skirt,black,jeans
setstate widgets 2017-08-27 13:37:44 15uzsuToggle OFF
setstate widgets 2017-09-01 10:44:22 16uzsuSelect shoes,skirt,jeans
setstate widgets 2017-08-31 00:28:20 17uzsuSelectRadio MW
setstate widgets 2017-12-31 08:30:45 18uzsuDropDown blue
setstate widgets 2017-08-24 20:54:43 19colorpicker ac2ab0
setstate widgets 2017-10-19 20:50:12 19colorpicker_BRI 100
setstate widgets 2017-10-07 07:56:31 19colorpicker_CT 5100
setstate widgets 2017-10-19 20:51:24 19colorpicker_HSV 822828
setstate widgets 2017-10-19 20:50:56 19colorpicker_HUE 185
setstate widgets 2017-10-19 20:50:47 19colorpicker_RGB 4b14ff
setstate widgets 2017-08-29 08:11:19 20time 12:00
setstate widgets 2019-07-30 20:08:01 21iconRadio 10
setstate widgets 2019-07-30 20:08:10 21iconRadio_use4icon 50
setstate widgets 2017-09-20 18:59:29 22iconButtons Wohnzimmer_1,Esszimmer,Gäste_WC,Wintergarten,Schlafzimmer
setstate widgets 2019-07-30 20:07:38 22iconSwitch half open
setstate widgets 2019-07-30 20:07:38 23iconLabel half open
setstate widgets 2017-09-01 11:40:52 23iconselectradio 10
setstate widgets 2019-07-30 20:07:47 24iconButtons Bad,Wohnzimmer_2,Diele,Büro,Werkstatt
setstate widgets 2019-07-30 20:07:49 24iconButtons_use4icon Wohnzimmer_1,Esszimmer,Büro,Werkstatt
setstate widgets 2019-08-06 13:48:37 25bitfield 0
setstate widgets 2017-11-25 01:41:29 iconSwitch half closed
setstate widgets 2017-11-25 01:42:52 state iconSwitch wide open
</pre>

== Beigesteuerte Widgets ==

* Forenthread [https://forum.fhem.de/index.php?topic=35736.0 neues DateTimePicker Widget] [[Datei:datetimepicker.png]]

[[Kategorie:Code Snippets]]
[[Kategorie:Glossary]]
[[Kategorie:HOWTOS]]

HMCCU

2021-04-28T12:09:00Z

ChristophMorrison: Fehlender Doppelpunkt in der Beschreibung zu ccuGetVars ergänzt

Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. {{Infobox Modul
|ModPurpose=Anbindung HomeMatic CCU an FHEM
|ModType=d
|ModCmdRef=HMCCU
|ModForumArea=HomeMatic
|ModTechName=88_HMCCU.pm
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])
}}
==Einführung==
===Übersicht===
Das Modul [[HMCCU]] ermöglicht zusammen mit den Client Modulen → [[HMCCUDEV]], HMCCUCHN und HMCCUPROCRPC eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:

* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU
* Unterstützung von HVL (HomeMatic Virtual Layer)
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben
* Lesen und Schreiben von CCU Systemvariablen
* Ausführen von CCU Programmen
* Ausführen von HomeMatic Scripts auf der CCU

Die einzelnen Module haben folgende Aufgaben:

* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen

===Geräte, Kanäle und Datenpunkte===
Geräte in der HomeMatic CCU bestehen aus einem oder mehreren Kanälen. Ein Kanal wiederum hat einen oder mehrere Datenpunkte. Über diese Datenpunkte kann ein Gerät gesteuert oder Statusinformationen ausgelesen werden. Sofern ein Datenpunkt lesbar ist, kann er als Reading in einem HMCCUCHN oder HMCCUDEV Device dargestellt werden. Ausgehend von dieser Abbildung in der CCU kann man nun entscheiden, ob man ein CCU Gerät mit HMCCUCHN oder HMCCUDEV definiert.

Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.

Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}

==Inbetriebnahme==
===Zu beachten===

* In den CCU Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.
* Namen in der CCU müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.
* Seit der CCU Firmware 2.27.7 sind die Zugriffsmöglichkeiten auf die CCU durch eine Firewall abgesichert. Der Zugriff durch FHEM muss explizit freigeschaltet werden, da HMCCU sonst nicht korrekt funktioniert (s. nächster Abschnitt).

===CCU Firewall Einstellungen===
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:
* Menü "Einstellungen > Systemsteuerung" aufrufen
* Button "Firewall konfigurieren" anklicken
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.
* Man kann die Rechte auf "Eingeschränkter Zugriff" belassen, muss dann aber im Feld "IP-Adressen für eingeschränkten Zugriff" die IP des FHEM-Servers oder das komplette Subnetz in Subnet-Notation angeben.

Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.

===Installation===
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client.

Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre>

Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren
<syntaxhighlight lang="doscon">
cpan install RPC::XML
</syntaxhighlight>
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code>

Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.

===Definition I/O Device===
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.
<pre>define d_ccu HMCCU 192.168.1.10</pre>
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Parameter ''ccudelay'' angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch ''ccudelay'' wird das neu angelegte I/O Device verzögert um die angegebene Anzahl Sekunden initialisiert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre>
Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist

===RPC Server konfigurieren===
Im nächsten Schritt wird der RPC-Server konfiguriert und gestartet. Zunächst werden mit dem Attribut ''rpcinterfaces'' die Schnittstellen bzw. Ports festgelegt, für die sich der RPC-Server bei der CCU registrieren soll. Folgende Angaben sind möglich:
* BidCos-RF
* BidCos-Wired
* HmIP-RF
* CUxD
* Homegear
* HVL
* VirtualDevices
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet. Im Internal "ccuinterfaces" werden nach der Definition des I/O Device alle verfügbaren Schnittstellen angezeigt.

Danach wird durch Setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.

'''Externer RPC-Server (HMCCURPCPROC)'''
Beim ersten Start dieses RPC-Servers über das I/O Device wird automatisch je Schnittstelle ein Device vom Typ HMCCURPCPROC angelegt. Die Attribute room und group werden vom I/O Device übernommen.

'''RPC-Server starten'''
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess mit eigenem Listening-Port gestartet. Beim ersten Start legt HMCCU für jede unter ''rpcinterfaces'' angegebene Schnittstelle ein Device vom Typ HMCCURPCPROC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.

Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:
<pre>set d_ccu rpcserver on</pre>
Während des Starts der RPC-Server und der Registrierung bei der CCU kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem die RPC-Server gestartet wurden, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:
<pre>attr d_ccu rpcserver on</pre>

===Vorgaben für Client Devices===
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:
{| class="wikitable"
|-
! Attribut in HMCCU !! Vorgabe für Attribut in HMCCUDEV/HMCCUCHN !! Default !! Bedeutung
|-
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1 |true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.
|-
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden
|-
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings
|-
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.
|}
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.

Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.

==Synchronisation mit der CCU==
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' liest alle Geräte aus der CCU. Er sollte immer ausgeführt werden, wenn sich an einer Gerätedefinition in der CCU etwas geändert hat, z.B. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.

Der Befehl '''get update''' liest die Datenpunkte aller in FHEM definierten HMCCUDEV und HMCCUCHN Devices aus der CCU und aktualisiert alle Readings aller Client Devices.

==Autocreate von Client Devices==
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre>
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.
Folgende ''Options'' sind möglich:
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.
An den Befehl kann eine Liste von Attributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.

Beispiel 1: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre>

Beispiel 2: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM" oder "Hm" (HmIP-Geräte) beginnt. Alle neuen FHEM Devices haben den Namen wie in der CCU und können dann mit dem Attribut "alias" verständlicher benannt werden. Sofern vorhanden, werden default Attribute gesetzt. Die Konfiguration wird gespeichert. Der Room "CCU_HM" ist angelehnt an "CUL_HM".
<pre>get d_ccu devicelist create ^H[M|m].* t=dev f=%n defattr save room=CCU_HM</pre>

==Verwaltung von Default Attributen==
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten HomeMatic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attributen eigene Vorlagendateien mit Default Attributen zu definieren.

===Anzeigen der Gerätetypen mit Default Attributen===
Mit dem Befehl '''get defaults''' im I/O Device werden alle HomeMatic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.

===Default Attribute exportieren und importieren===
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:
<pre>
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt

... Datei /opt/fhem/hmccu_defattr.txt editieren ...

set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt
</pre>
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.

===Benutzerdefinierte Attribute löschen===
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.

==Weitere Funktionen des Moduls HMCCU==
===Lesen und Ändern von CCU Systemvariablen===
Systemvariablen der CCU können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden. Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert.

Beispiel: Lesen aller Systemvariablen, die mit A beginnen:
<pre>get d_ccu vars A.*</pre>

Systemvariablen können in regelmäßigen Abständen gelesen werden. Dazu wird mit dem Attribut ccuGetVars ein Intervall und optional ein regulärer Ausdruck für die zu lesenden Systemvariablen festgelegt.

Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:
<pre>attr d_ccu ccuGetVars 60
attr d_ccu ccuGetVars 60:^A</pre>

Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.

Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:
<pre>set d_ccu var Temperatur 20.5</pre>

Mit dem Befehl '''set var''' kann auch eine neue Systemvariable in der CCU angelegt werden. Dazu wird als erster Parameter vor dem Variablennamen der Typ der neuen Variable angegeben. Mögliche Typen sind "bool", "list", "number" oder "text".

Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":
<pre>set d_ccu var text Wetter sonnig</pre>

Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:

* unit = Einheit
* desc = Beschreibung
* min = Kleinster erlaubter Wert bei numerischen Variablen
* max = Größter erlaubter Wert bei numerischen Variablen
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"

Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre>

===Ausführen von CCU Programmen===
Ein in der CCU2 hinterlegtes Programm kann mit dem Befehl '''set execute''' ausgeführt werden. Einziger Parameter des Befehls ist der Name des Programms. Es spielt keine Rolle, ob das Programm in der CCU aktiv oder inaktiv ist.

Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:
<pre>set d_ccu execute Schalter_Ein</pre>

===Aggregation von Gerätezuständen (ab 3.6)===
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?
* Wieviele und welche Fenster sind geöffnet?
Für die Beantwortung dieser Fragen stellt HMCCU einige Befehle und Attribute bereit. Die Ergebnisse werden in Form von Readings im I/O Device bereitgestellt:
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).
Aggregationen werden automatisch bei Änderung von Readings neu berechnet. Alternativ kann mit dem Befehl '''get aggregation''' eine Aggregation explizit durchgeführt werden. Als Parameter wird der Name der Aggregationsregel oder "all" für alle Aggregationen übergeben:
<pre>get <io-dev> aggregation {all|<name>}</pre>
Die Konfiguration der Aggregationen erfolgt mit Hilfe von Regeln, die über das Attribut ''ccuaggregate'' definiert werden. Dabei werden mehrere Regeln durch ein Semikolon und optional einen Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:
*'''name''':<Name> - Legt den Namen einer Aggregation fest.
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:
**name: FHEM Device Name
**alias: FHEM Device Alias
**group: FHEM Device ''group'' Attribut
**room: FHEM Device ''room'' Attribut
**type: HomeMatic Gerätetyp
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.
*'''else''':<Value>
*'''prefix''':{RULE|<Text>} - Legt das Präfix für die Readings fest, die das Ergebnis einer Aggregation beinhalten wobei "RULE" für den Namen der Aggregationsregel steht.
*'''coll''':{NAME|<Attribute>}[!<Default>] - Legt fest, welches Attribut der FHEM Devices, die in die Aggregation einbezogen werden, in das _list Reading aufgenommen werden, sofern sie die if Bedingung erfüllen. Dabei entspricht "NAME" dem FHEM-Devicename. Der optionale Parameter Default legt den Inhalt des _list Readings fest, wenn keines der FHEM Devices die if Bedingung erfüllt. Voreingestellt ist "no match".

Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):
<pre>
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias
</pre>
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):
<pre>
battery_count: 50
battery_list: Fenster Bad,Fenster Wohnzimmer
battery_match: 2
battery_state: yes
</pre>

===Ausführen von HomeMatic Scripts===
Mit dem Befehl '''set hmscript''' kann ein beliebiges HomeMatic Script an die CCU2 zur Ausführung gesendet werden. Wenn das Script zeilenweise Daten im Format "Parameter=Value" zurück gibt, werden diese als Readings mit dem Namen ''Parameter" im I/O Device gespeichert.''

Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):
<pre>
object osysvar;
string ssysvarid;
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())
{
osysvar = dom.GetObject(ssysvarid);
WriteLine (osysvar.Name() # "=" # osysvar.Value());
}
</pre>

Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:

<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre>

[[Kategorie:HomeMatic Components]]
[[Kategorie:Interfaces]]

CsrfToken-HowTo

2021-03-27T10:26:36Z

ChristophMorrison: Webhook sinnvoll eingebaut

{{SEITENTITEL:csrfToken-HowTo}}
==Vorbemerkung==
FHEM hat mit der Version 5.8 eine Sicherheitsmaßnahme scharfgeschaltet, den csrfToken.
Dieser Token wird bei jedem Neustart von FHEM neu gebildet.

Dieses Feature erhöht die Sicherheit (siehe Links ganz unten), führt aber dazu, dass man nicht mehr (wie in älteren Anleitungen beschrieben), mit einem statischen http Link Steuerbefehle (auch Webhooks) an das [[FHEMWEB]] senden kann.

'''Beispiel'''

Schalte den "Schalter" Office auf on. Das ging früher ohne CsrfToken einfach durch diesen HTML String - egal ob im Browser, in Windows, auf dem Mac, auf der Kommandozeile mit wget usw.
:<syntaxhighlight lang="html">http://hostname:8083/fhem?cmd=set%20Office%20on</syntaxhighlight>
Mit CsrfToken müsste diese Zeile so aussehen (Beispiel, der Token ändert sich bei jedem Start von FHEM):
:<syntaxhighlight lang="html">http://hostname:8083/fhem?cmd=set%20Office%20on&fwcsrf=csrf_196525024154371</syntaxhighlight>
Ist der CsrfToken falsch (weil durch Neustart geändert) erfolgt keine Reaktion Schalters und es gibt eine (ähnliche) Fehlermeldung im FHEMLog:
2019.10.24 12:08:13 3: FHEMWEB WEB CSRF error: csrf_104345683644172 ne csrf_148832911104462 for client WEB_192.168.178.20_54197 ...
''Diese Fehlermeldung kann selten auch so beim Neustart auftauchen, wenn ein Browser Fenster mit altem Token nach einem "shutdown restart" einfach nur einen Refresh macht.''

Soll ein http: Link zum Steuern von FHEM verwendet werden, gibt es folgende Lösungsansätze:

==Codebeispiele==
===Einzeiler Shell===

Entweder mit curl oder wget

:<syntaxhighlight lang="bash">curl -s -D - 'http://localhost:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}'
wget -qO - --server-response 'http://localhost:8083/fhem?XHR=1' 2>&1 | awk '/X-FHEM-csrfToken/{print $2}'</syntaxhighlight>

kann man den aktuellen csrfToken aus dem Header extrahieren und muss ihn nur noch an den Aufruf anhängen.

Erste Variante mit curl:

:<syntaxhighlight lang="bash">curl --data "fwcsrf=$(curl -s -D - 'http://localhost:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}')" http://localhost:8083/fhem?cmd=set%20Office%20on</syntaxhighlight>

Oder mit mehr Komfort (eigentlich ein Mehrzeiler): Nur Einmal die Angabe des Hostnamen und den FHEM Befehl normal mit Leerzeichen angeben:
:<syntaxhighlight lang="bash">h='Name oder IP:PortNr'; c='FHEM Befehl'; curl --data "fwcsrf=$(curl -s -D - http://$h/fhem?XHR=1 | awk '/X-FHEM-csrfToken/{print $2}')" http://$h/fhem?cmd=$(echo $c|sed 's/ /%20/g')</syntaxhighlight>

Ein übersichtlicher Mehrzeiler mit wget. Als Beispiel wird vom localhost:8083 ein "list global" ohne HTML ausgegeben:

:<syntaxhighlight lang="bash">hosturl="http://localhost:8083"
cmd=list%20global
token=$(wget -qO - --server-response "$hosturl/fhem?XHR=1" 2>&1 | awk '/X-FHEM-csrfToken/{print $2}')
wget -q -O - "$hosturl/fhem?cmd=$cmd&fwcsrf=$token&XHR=1"</syntaxhighlight>

Man kann auch noch den token vom cr+lf am Ende befreien:

:<syntaxhighlight lang="bash">curl "http://fhem.example.org:8083/fhem?cmd=set%20Office%20on&XHR=1&fwcsrf="`curl -s -D - 'http://fhem.example.org:8083/fhem?XHR=1' | awk '/X-FHEM-csrfToken/{print $2}' | tr -d "\r\n"`</syntaxhighlight>

===Innerhalb FHEM mit Perl===
FHEM kennt natürlich seinen Token und man hat einfachen Zugriff mit der Variable $FW_CSRF. Diese Varibale enthält nicht den Token an sich, sondern den kompletten String zum Anhängen an eine URL in der Form: &fwcsrf=csrf_387849633005507

Beispiel (funktioniert auch in der FHEM Kommandozeile)
:<syntaxhighlight lang="perl">{my $button_test = "<a href='http://localhost:8083/fhem?cmd=set%20Office%20on$FW_CSRF'>test</a>"}
</syntaxhighlight>

=== Perl Sub ===
Innerhalb von Perl geht die Abfrage eines anderen FHEM Servers natürlich auch:<syntaxhighlight lang="perl">
sub fhemcl
{
use URI::Escape;
use LWP::UserAgent;
# if url is empty, localhost and default port is used
my $fhemcmd = shift // return "Usage: fhemcl('fhem cmd'[,'urlToHost']) - like fhemcl('set Test2 toggle','http://host:8083')\n";
my $hosturl = shift || 'http://localhost:8083';
my $token;
# get token
my $ua = new LWP::UserAgent;
my $url = "$hosturl/fhem?XHR=1/";
my $resp = $ua->get($url);
$token = $resp->header('X-FHEM-CsrfToken');
# url encode the cmd
$fhemcmd = uri_escape($fhemcmd);
$url = "$hosturl/fhem?cmd=$fhemcmd&fwcsrf=$token&XHR=1";
$resp = $ua->get($url)->content;
# cut the last character: the additional newline
return substr $resp,0,-1
}
</syntaxhighlight>

===Raw Import in der Shell===
Will man ganze Definitionsblöcke von der System Kommandozeile importieren, kann man dieses Script verwenden. Im übergebenen Dateinamen sind Zeilenweise die FHEM Befehle gespeichert. Bei Bedarf kann man auch einen anderen Hostnamen und ein anderes Port angeben. Der Token wird zu Beginn ermittelt. Die Leerzeichen werden für HTTP durch %20 ersetzt.
:<syntaxhighlight lang="bash">
#!/bin/bash
# fhemraw Import analog Raw Definition
if [ $# -eq 0 ] ; then
echo fhemraw bitte so verwenden
echo fhemraw <dateiName> [<hostName>] [<portNummer>]
exit 1
fi

if [ -z $2 ] ; then
fhemhost=localhost
else
fhemhost=$2
fi
if [ -z $3 ] ; then
fhemhost=$fhemhost:8083
else
fhemhost=$fhemhost:$3
fi
token=$(curl -s -D - "http://$fhemhost/fhem?XHR=1" | awk '/X-FHEM-csrfToken/{print $2}')

while read line
do
curl --data "fwcsrf=$token" http://$fhemhost/fhem?cmd=$(echo $line|sed 's/ /%20/g')
done < $1
</syntaxhighlight>

===Python===
Falls mal jemand aus python (hier für python 2.7) heraus fhem ansteuern möchte

<syntaxhighlight lang="Python">
import sys
import urllib2
import urllib
import ssl
import urlparse
BASEURL = 'https://user:password@server_ip:8083/fhem?'
url = BASEURL + 'cmd=set+licht+on'
def get_token(url):
nurl = urlparse.urlsplit(url)
username = nurl.username
password = nurl.password
url = url.replace(username + ':' + password + '@', '')
url = url.replace(" ", "%20")
ssl._create_default_https_context = ssl._create_unverified_context
p = urllib2.HTTPPasswordMgrWithDefaultRealm()
p.add_password(None, url, username, password)
handler = urllib2.HTTPBasicAuthHandler(p)
opener = urllib2.build_opener(handler)
urllib2.install_opener(opener)
try:
uu = urllib2.urlopen(
url=url,
data=None,
timeout=10
)
token = uu.read()
token = token[token.find('csrf_'):]
token = token[:token.find("\'")]
return token
except urllib2.URLError, urllib2.URLError.reason:
print('URLError: %s' % urllib2.URLError.reason)
return False

def fire_command(url):
# type: (object) -> object
if "@" in url:
token = get_token(BASEURL)
data = {'fwcsrf': token}
data = urllib.urlencode(data)
nurl = urlparse.urlsplit(url)
username = nurl.username
password = nurl.password
url = url.replace(username + ':' + password + '@', '')
url = url.replace(" ", "%20")
ssl._create_default_https_context = ssl._create_unverified_context
p = urllib2.HTTPPasswordMgrWithDefaultRealm()
p.add_password(None, url, username, password)
handler = urllib2.HTTPBasicAuthHandler(p)
opener = urllib2.build_opener(handler)
urllib2.install_opener(opener)
try:
urllib2.urlopen(
url=url,
data=data,
timeout=10
)
except urllib2.URLError, urllib2.URLError.reason:
print('URLError: %s' % urllib2.URLError.reason)
return False
</syntaxhighlight>

==Alternative Konfiguration==
===API Web===
Falls man ohne den Token arbeiten will, könnte man ein eigenes API Web erstellen und den Zugriff darauf beschränken. In vorhandenen Scripten / Applikationen müsste dann lediglich der Port geändert werden.

define WEBapi FHEMWEB 8088 global
attr WEBapi csrfToken none
attr WEBapi allowfrom 192.168.178.83|127.0.0.1

Im Forum ist beschrieben wie man die Gestaltung des regEx für die IP Adresse machen kann ({{Link2Forum|Topic=23994}}).
Einen regEx Builder für IP-Ranges findet man unter
[http://www.analyticsmarket.com/freetools/ipregex]

===csrfToken festlegen===
Dies kann man tun, falls die dynamische Abfrage zur Laufzeit des Tokens nicht möglich ist.
:<code><nowiki>attr WEB.* csrfToken <beliebige Folge aus Zeichen und Zahlen></nowiki></code>

Damit können feste URLs verwendet werden:
:<code><nowiki>http://localhost:8083/fhem?cmd=set%20Office%20on&fwcsrf=<fester token></nowiki></code>

===csrfToken abschalten===
Dies sollte man als erste Hilfe tun, aber unbedingt darüber nachdenken wie man die Applikation umstellt.
:<code>attr WEB.* csrfToken none</code>

===Featurelevel===
Eine weitere temporäre Notfallmaßnahme wäre den Featurelevel nach dem Update einfach wieder zurückzudrehen
:<code>attr global featurelevel 5.7</code>

==Links==
* Automatisch das korrekte Token in Weblink einbinden: {{Link2Forum|Topic=67543|Message=590584}}
* [https://de.wikipedia.org/wiki/Cross-Site-Request-Forgery Wikipedia - Cross Site Request Forgery (csrf)]
* [http://heinz-otto.blogspot.de/2017/03/csrf-token-und-fhem.html Blog-Beitrag zu csrf-Token und FHEM]

[[Kategorie:HOWTOS]]
[[Kategorie:Glossary]]

DevelopmentModuleAPI

2021-03-02T17:55:32Z

ChristophMorrison: Fehlende Parameter für parseParams() dokumentiert

{{Randnotiz|RNTyp=r|RNText=Bitte beachten: Diese Auflistung von Funktionen wird nicht aktiv durch alle Entwickler gepflegt. Es kann daher keine Garantie auf Vollständigkeit und Korrektheit gegeben werden. Letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im [https://forum.fhem.de/index.php/board,80.0.html FHEM-Forum] angemerkt werden!
<hr />
Please note: This list of functions is not officially maintained by all developers. So there is no guarantee for completeness and correctness. In the end it is always the Perl code itself that is relevant; please report errors and omissions in the [https://forum.fhem.de/index.php/board,80.0.html FHEM forum]!
}}
Dieses Seite soll eine Beschreibung der für Moduleentwickler verfügbaren Funktionen enthalten, um für Modulentwickler
* Wiederverwendbare Routinen leichter identifizieren zu können
* Durch Wiederverwendung mehr Einheitlichkeit zu erzeugen
* Aufwand zu verringern
* Bei Änderungen auch betroffene Module leichter identifizieren zu können

Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über eine Funktion stolpert, die auch andere interessieren könnte.

== FHEM-Befehlsausführung ==

=== AnalyzeCommand ===

:<syntaxhighlight lang="perl">$error = AnalyzeCommand($client_hash, $cmd);</syntaxhighlight>

AnalyzeCommand() ermöglicht das Parsen und die Ausführung eines einzelnen FHEM-Befehls.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando <code>$cmd</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>). Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Ein einzelnes Kommando, welches ausgeführt werden soll (ACHTUNG: keine Kommando-Ketten!!!). 
Beispiel:
* <code>define dummy1 dummy</code>
* <code>{Log3(undef, 1, "Hallo")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehlermeldungen, die beim Ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzeCommandChain ===
AnalyzeCommandChain() ermöglicht die Ausführung von FHEM-Befehlsketten. Dabei werden mehrere FHEM-Kommandos durch ein Semikolon getrennt und nacheinander mittels AnalyzeCommand() ausgeführt.
:<source lang="perl">$errors = AnalyzeCommandChain ($client_hash, $cmds)</source>

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Kommandokette, welche ausgeführt werden soll, durch <code>;</code> getrennt. 
Beispiel:
* <code>define dummy1 dummy; list dummy1; {Log(3,"dummy created")}</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== AnalyzePerlCommand ===

:<syntaxhighlight lang="perl">$errors = AnalyzePerlCommand ($client_hash, $cmds);</syntaxhighlight>

AnalyzePerlCommand() ermöglicht die Ausführung von Perl-Kommandos/Routinen. Sofern "$client_hash" angegeben wurde, wird die Authorisierung geprüft (man kann mit allowed die Ausfuehrung von perl untersagen).
Mehrere Kommandos sind innerhalb von "$cmds" durch Semikolon zu trennen.

Sollten Warnung bei der Ausführung der Perl-Kommandos auftreten, werden sie im FHEM-Logfile mit verbose-Level "1" ausgegeben.

Sind [[#EvalSpecials|EvalSpecials()]] definiert, können diese Definitionen innerhalb des übergebenen Perl-Codes verwendet werden.
Ebenfalls werden die Variablen $we (siehe holiday2we), $sec,$min,$hour,$mday,$month,$year,$wday,$yday,$isdst (siehe Perl localtime) sowie $hms (Zeit im sprintf-Format "hh:mm:ss") generiert und können somit im auszuführenden Code verwendet werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory can be <code>undef</code>''
|| Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos <code>$cmds</code> ausführen darf (Vorgangs-Typ: <code>cmd</code>).Der Definition-Hash muss in <code>SNAME</code> den zum Attribut <code>validFor</code> (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert <code>undef</code> übergeben wird, erfolgt keine Prüfung.
|-
|-
| style="vertical-align:top" | '''<code>$cmds</code>'''

''mandatory''
|| Perl-Kommando(s), welche ausgeführt werden sollen, durch <code>;</code> getrennt. 
Beispiel:
* <code> my $ignore; if($we) {$ignore=1} </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$errors</code>'''
|| Fehlermeldungen, die beim Ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird <code>undef</code> zurückgegeben.
|}

=== EvalSpecials ===

:<syntaxhighlight lang="perl">$final_cmd = EvalSpecials($cmd, %specials);</syntaxhighlight>
EvalSpecials() ermöglicht die Ersetzung von Platzhaltern in FHEM-Befehlen, welche durch AnalyzeCommandChain() zur Ausführung gebracht werden sollen. Dabei werden alle Schlüssel von <code>%specials</code> in <code>$cmd</code> gesucht und durch die entsprechenden Werte aus <code>%specials</code> ersetzt.

Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut <code>featurelevel</code>) unterschiedliches Verhalten um die Kompatibilität mit früheren FHEM-Versionen und deren Konfiguration zu wahren.

In jedem Falle muss der zurückgegebene String mit AnalyzeCommandChain() zur Ausführung gebracht werden.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.

Bsp: <code>set $NAME power on; {Log(3, "power on $NAME for $ADDRESS")}</code>
|-
| style="vertical-align:top" | '''<code>%specials</code>'''

''mandatory''
|| Hash, welcher als Schlüssel die zu ersetzenden Platzhalter-Namen den zu ersetzenden Werten zuordnet. Jeder Schlüssel ist aus historischen Gründen mit einem Prozentzeichen zu beginnen. Die Platzhalter müssen zusammenhängend sein und dürfen nur aus Zahlen, Buchstaben und Unterstrichen (<code>_</code>) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.

Bspw: <code>("%NAME" => "Definition_A", "%ADDRESS" => "192.168.0.2") </code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$final_cmd</code>'''
|| Das fertige Kommando, welches so direkt an AnalyzeCommandChain() übergeben werden muss.

Ab Featurelevel 5.7 sind die Platzhalter in diesem String nicht ersetzt. Die Ersetzung wird in diesem Fall in AnalyzeCommandChain() vorgenommen, wo die einzelnen Platzhalter ersetzt werden. Die Funktion EvalSpecials() speichert in diesem Falle nur den Hash im Hintergrund, die eigentliche Ersetzung wird dann durch AnalyzeCommandChain() und deren untergeordneten Funktionen übernommen.

In Featurelevel 5.6 und vorher wird ein Suchen/Ersetzen der Platzhalter in EvalSpecials() selbst vorgenommen. Hierbei ist der zurückgegebene String das finale Kommando, welches keine Platzhalter mehr beinhaltet.
|}

=== parseParams ===

<ul><syntaxhighlight lang="perl">my($a, $h) = parseParams($cmd);
my($a, $h) = parseParams($cmd, $separator, $joiner, $keyvalueseparator);
</syntaxhighlight></ul>

parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.B. für die Parameter von define ([[DevelopmentModuleIntro#X_Define|DefineFn]]), get ([[DevelopmentModuleIntro#X_Get|GetFn]]) und set ([[DevelopmentModuleIntro#X_Set|SetFn]]) verwenden. Beim Parsen werden erkannt:
* einfache, durch den Separator getrennte, Zeichenfolgen
* benannte Parameter der Form <code><name>=<wert></code>
** Werte können in einfache (<code>'</code>) oder doppelte (<code>"</code>) Anführungszeichen eingeschlossen sein, um so den jeweiligen Separator zu enthalten
** Ein solches Pärchen aus gleichen Anführungszeichen an Anfang und Ende eines Wertes wird beim Parsen entfernt.
* in <code>{...}</code> eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleiche Anzahl öffnender und schliessender Klammern erreicht ist.

In der Modul <code>X_Initialize</code> Routine lässt sich mit <code>$hash->{parseParams} = 1;</code> festlegen, dass parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebnis an die DefFn, GetFn und SetFn übergeben wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$cmd</code>'''

''mandatory''
|| Die Argumente des Kommandos als String oder als Array-Referenz.

|-
| style="vertical-align:top" | '''<code>$separator</code>'''

''optional''
|| Der Separator, an dem die Parameterzeile in einzelne Parameter gesplittet werden soll. Dieser Parameter wird nur beachtet, wenn die Argumente als Zeichenkette übergeben werden.

Standardwert: ' ' ''(Leerzeichen)''
|-
|'''<code>$joiner</code>'''
''optional''
|
|-
|'''<code>$keyvalueseparator</code>'''
''optional''
|Trennzeichen, das <name>- von <wert>-Paaren trennt, Standardwert ist '='
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$a</code>'''
|| Eine Referenz auf ein Array, das alle nicht benannten Parameter in der Reihenfolge ihres Vorkommens enthält.

|-
| style="vertical-align:top" | '''<code>$h</code>'''
|| Eine Referenz auf einen Hash, der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. (Achtung: Ein Hash ist nicht sortiert!)
|}

Beispiel: Die Zeile
:<code>set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }</code>
wird in die folgenden Elemente geparst:
<syntaxhighlight lang="perl">
# Die nicht benannten Parameter:
$a = [
'set',
'<name>',
'test1',
'test3',
'test4 test4',
'{my $x = "abc"}'
];

# Die benannten Parameter:
$h = {
'test10' => '{ { my $abc ="xyz" } }',
'test5' => 'test5 test5',
'test8' => '\'',
'test2' => 'abc',
'test7' => '',
'test9' => '"',
'test6' => 'test6=test6'
};
</syntaxhighlight>

=== asyncOutput ===

:<syntaxhighlight lang="perl">asyncOutput($client_hash, $message);</syntaxhighlight>

Mit der Funktion asyncOutput() kann man an einen bestimmten Client (FHEMWEB oder telnet) gezielt Daten übermitteln, die auf diesem Client angezeigt werden sollen. Damit können Kommandos via FHEMWEB oder Telnet gestartet werden und das Ergebnis zu einem späteren Zeitpunkt zurückgegeben werden. Ebenso können so Daten angefordert werden und erst zum Zeitpunkt des Eintreffens via asyncOutput() an den entsprechenden Client weitergeleitet werden.

Um diese Funktion nutzen zu können, muss das Modul, über das eine Client-Verbindung besteht, eine [[DevelopmentModuleIntro#X_AsyncOutputFn|AsyncOutputFn]] bereitstellen. Dies wird aktuell nur in [[FHEMWEB]] und telnet unterstützt. Man kann die Unterstützung für eine asynchrone Datenübermittlung vorab mittels einer if-Abfrage auf<code>$client_hash->{canAsyncOutput}</code> prüfen, da es durchaus passieren kann, dass unter bestimmten Umständen keine asynchrone Übertragung möglich ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Die Hash-Referenz der Client-Instanz (telnet- oder FHEMWEB-Instanz), auf das die Ausgabe erfolgen soll. Dieser Client-Hash wird beim Aufruf der [[DevelopmentModuleIntro#X_Set|SetFn]] und [[DevelopmentModuleIntro#X_Get|GetFn]] unter <code>$hash->{CL}</code> bereitgestellt.

|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Daten als Zeichenkette, welche ausgegeben werden sollen.

|}

=== SetExtensions ===

:<syntaxhighlight lang="perl">$error = SetExtensions($hash, $usage_list, @set_args);</syntaxhighlight>

Die Funktion SetExtensions() wird durch das Hilfsmodul SetExtensions.pm bereitgestellt und implementiert weiterführende Set-Befehle basierend auf den Grundbefehlen <code>on</code> und <code>off</code>. Sie wird ausschließlich im Rahmen der Modulprogrammierung in der [[DevelopmentModuleIntro#X_Set|Set]]-Funktion verwendet.

Ein Implementierungsbeispiel gibt es im Wiki-Artikel zur [[DevelopmentModuleIntro#X_Set|Set]]-Funktion.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Gerätedefinition, für die gerade die [[DevelopmentModuleIntro#X_Set|Set]]-Funktion ausgeführt wird.
|-
| style="vertical-align:top" | '''<code>$usage_list</code>'''

''mandatory''
|| Die Auflistung aller möglichen Kommandos als Zeichenkette, welche innerhalb der Set-Funktion unterstützt werden. Es handelt sich hierbei nur reinweg um die Auflistung der Kommandos ohne das Präfix <code>unknown command ''[...]'' choose one of</code>. Diese Liste muss mind. die Befehle <code>on</code> und <code>off</code> enthalten, damit SetExtensions() zusätzliche Set-Befehle anbieten kann. Es können hierbei FHEMWEB-spezifische Widget-Optionen verwendet werden.

Beispiel:
* <code>"on off statusRequest"</code>
* <code>"on:noArg off:noArg input:av1,av2,av3 volume"</code>
|-
| style="vertical-align:top" | '''<code>@set_args</code>'''

''mandatory''
|| Sämtliche Argumente, welche an die Set-Funktion übergeben wurden (ausser <code>$hash</code>). Dieses Array entspricht einem Array aus den Parametern <code>($name, $cmd, @args)</code> aus dem [[DevelopmentModuleIntro#X_Set|Artikel zur Set-Funktion]]
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>'''
|| Fehler- bzw. Usage-Meldung, die beim Ausführen von SetExtensions() aufgetreten ist. Diese Rückmeldung muss direkt als Rückgabewert der Set-Funktion verwendet werden.
|}

Siehe auch: [[DevelopmentModuleAPI#SetExtensionsCancel|SetExtensionsCancel]]

== Time / Timestamp ==

=== FmtDateTimeRFC1123===

<ul><syntaxhighlight lang="perl">$timestampGMT = FmtDateTimeRFC1123($timestamp);</syntaxhighlight>
</ul>
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestampGMT </code>'''

|| Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. 
<code>Sat, 05 Mar 2016 18:17:48 GMT</code>
|}

=== FmtDateTime===

:<syntaxhighlight lang="perl">$timestamp = FmtDateTime($time);</syntaxhighlight>
Wandelt einen UNIX-Timestamp (Sekunden seit Beginn der UNIX-Epoche: 01.01.1970 00:00:00 UTC) in eine formatierte Angabe in der lokalen Zeitzone um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$time</code>'''

''mandatory''
|| Zeitangabe wie sie von der <code>time()</code> Funktion zurückgegeben wird. 

Bsp: <code>1457201868</code>
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code>
|}

=== TimeNow ===

:<syntaxhighlight lang="perl">$timestamp = TimeNow();</syntaxhighlight>

Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

|| Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format 
<code>2016-02-16 19:34:24</code> 

Benutzt die Funktion <code>FmtDateTime()</code>
|}

=== fhemTimeGm===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion <code>gmtime()</code> erzeugt wird, in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

=== fhemTimeLocal===

:<syntaxhighlight lang="perl">$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year);</syntaxhighlight>
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion <code>localtime()</code> erzeugt wird in einen UNIX-Timestamp um.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$sec</code>'''

''mandatory''
|| Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$min</code>'''

''mandatory''
|| Die Minuten-Komponente als Ganzzahl zwischen 0 und 59.
|-
| style="vertical-align:top" | '''<code>$hour</code>'''

''mandatory''
|| Die Stunden-Komponente als Ganzzahl zwischen 0 und 23.
|-
| style="vertical-align:top" | '''<code>$mday</code>'''

''mandatory''
|| Die Tag-Komponente als Ganzzahl zwischen 1 und 31.
|-
| style="vertical-align:top" | '''<code>$month</code>'''

''mandatory''
|| Die Monats-Komponente als Ganzzahl zwischen 0 und 11. Hier erfolgt eine andere Zuordnung. Der Januar entspricht der 0, Februar der 1, usw. Der Dezember entspricht dem Wert 11.
|-
| style="vertical-align:top" | '''<code>$year</code>'''

''mandatory''
|| Die Jahres-Komponente. Das Jahr wird dabei nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp </code>'''

|| Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) 
Bsp: <code>1457201868</code>
|}

== Readings / Events ==

=== readingsBeginUpdate ===

:<syntaxhighlight lang="perl">
readingsBeginUpdate($hash);
</syntaxhighlight>
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash <code>$hash</code> auf ein Update von Readings vor. Dies betrifft insbesondere das Setzen von Umgebungsvariablen sowie dem aktuellen Zeitstempel als Änderungszeitpunkt. Der Aufruf dieser Funktion ist notwendig um eigentliche Updates mit der Funktion readingsBulkUpdate() auf der gewünschten Definition durchführen zu können.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>''' || Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|}

=== readingsBulkUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: [[event-on-change-reading]], [[event-on-update-reading]], [[event-min-interval]], ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsBulkUpdateIfChanged ===

<ul><syntaxhighlight lang="perl">
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value);
$rv = readingsBulkUpdateIfChanged($hash, $reading, $value, $changed);
</syntaxhighlight></ul>
Die Funktion readingsBulkUpdateIfChanged() führt ein Update eines einzelnen Readings für die Definition <code>$hash</code> durch, sofern sich der neue Wert <code>$value</code> gegenüber dem vorherigen Wert verändert. Dabei wird das Readings <code>$reading</code> auf den Wert <code>$value</code> gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt. Nur, sobald sich der Wert des Readings verändert, wird die Funktion readingsBulkUpdate() ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$changed</code>'''

''optional''
|| Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: <code>1</code>). Oder ob definitiv kein Event erzeugt werden soll (Wert: <code>0</code>). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von <code>$hash</code> entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. Sofern der alte Wert dem neuen Wert entspricht, wird <code>undef</code> zurückgegeben.
|}

=== readingsEndUpdate ===

<ul><syntaxhighlight lang="perl">
readingsEndUpdate($hash, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsEndUpdate() beendet den Bulk-Update Prozess durch die Funktionen readingsBeginUpdate() & readingsBulkUpdate() und triggert optional die entsprechenden Events sämtlicher erzeugter Readings für die Definition <code>$hash</code>. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: <code>userReadings</code>), sowie die Erzeugung des STATE aufgrund des Attributs <code>stateFormat</code> durchgeführt. Sofern <code>$do_trigger</code> gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo Readings geupdatet wurden.
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: <code>1</code>). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|}

=== readingsSingleUpdate ===

<ul><syntaxhighlight lang="perl">
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
</syntaxhighlight></ul>
Die Funktion readingsSingleUpdate() führt ein einzelnes Reading-Update mithilfe der Funktionen readingsBeginUpdate(), readingsBulkUpdate() und readingsEndUpdate() durch. Es entspricht dabei einem Aufruf aller 3 Funktionen nacheinander mit den entsprechenden einzelnen Parametern in den jeweiligen Funktionen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches geupdatet werden soll
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory''
|| Der Wert, welchen das Reading annehmen soll
|-
| style="vertical-align:top" | '''<code>$do_trigger</code>'''

''mandatory''
|| Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: <code>1</code>, Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird kein Event erzeugt.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$rv</code>''' || Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde.
|}

=== readingsDelete ===

<ul><syntaxhighlight lang="perl">
readingsDelete($hash, $reading);
</syntaxhighlight></ul>
Die Funktion readingsDelete() löscht das Reading <code>$reading</code> aus der Definition <code>$hash</code>.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, wo das Reading gelöscht werden soll
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Name des Readings, welches gelöscht werden soll
|}

=== DoTrigger ===

<ul><syntaxhighlight lang="perl">
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
</syntaxhighlight></ul>
Die Funktion DoTrigger() triggert alle angesammelten Events in <code>$hash->{CHANGED}</code> sowie zusätzlich das Event <code>$new_state</code> für die Definition <code>$name</code> und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in <code>$hash->{CHANGED}</code> keine zu bearbeitenden Änderungen enthalten sind, wird lediglich <code>$new_state</code> getriggert (sofern gesetzt).

Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Name der Definition deren Events durchgeführt werden sollen.
|-
| style="vertical-align:top" | '''<code>$new_state</code>'''

''mandatory''
|| Das Event welches zusätzlich zu bereits anstehenden Events aus <code>$hash->{CHANGED}</code> getriggert werden soll. Wenn dieser Wert <code>undef</code> ist, werden nur alle Events aus <code>$hash->{CHANGED}</code> bearbeitet, sofern <code>$hash->{CHANGED}</code> gefüllt ist.
|-
| style="vertical-align:top" | '''<code>$no_replace</code>'''

''optional''
|| Optionales Flag, welches die Ersetzung von Events durch das Attribut <code>eventMap</code> verhindert (Wert: <code>1</code>).

|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' || Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben.
|}

=== deviceEvents ===

<ul><syntaxhighlight lang="perl">
$events = deviceEvents($hash, $with_state);
</syntaxhighlight></ul>
Die Funktion deviceEvents() gibt alle anstehenden Events für die Definition <code>$hash</code> als Array-Referenz zurück. Diese Funktion ist bei der Modulentwicklung primär zur Nutzung in der [[DevelopmentModuleIntro#X_Notify|NotifyFn]] vorgesehen, um die anstehenden Events zu ermitteln.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, deren anstehende Events zurückgegeben werden sollen.
|-
| style="vertical-align:top" | '''<code>$with_state</code>'''

''mandatory can be <code>undef</code>''
|| Flag, ob das Reading <code>state</code> mit dem Readingnamen in der zurückgegebenen Event-Liste erscheinen soll (Wert: <code>1</code>) oder nur der Wert ohne dem vorangestellten Readingnamen "<code>state: </code>" (Wert: <code>0</code>) in der Event-Liste angezeigt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$events</code>''' || Eine Array-Referenz, welche alle anstehenden Events als Liste bereitstellt. Sofern keine Events anstehen, ist der Rückgabewert <code>undef</code>.

Bsp. (mit <code>$with_state = 0</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>

Bsp. (mit <code>$with_state = 1</code>):
<ul>

<syntaxhighlight lang="perl">
[
"humidity: 84",
"state: T: 10.5 H: 84",
"temperature: 10.5"
]
</syntaxhighlight></ul>
|}

=== notifyRegexpChanged ===

<ul><syntaxhighlight lang="perl">
notifyRegexpChanged($hash, $event_regexp);
</syntaxhighlight></ul>
Die Funktion notifyRegexpChanged() setzt für <code>$hash</code> einen passenden Eintrag in <code>$hash->{NOTIFYDEV}</code> basierend auf dem regulären Ausdruck <code>$event_regexp</code>, welcher üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] als Argument übergeben wird. Dadurch wird die [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] nur für Events der entsprechenden Gerätedefinition aufgerufen.

Je nach dem, wie <code>$event_regexp</code> formuliert ist, setzt notifyRegexpChanged() einen Eintrag in <code>$hash->{NOTIFYDEV}</code>. Es kann durchaus vorkommen, dass kein Eintrag in NOTIFYDEV gesetzt wird, da nicht zweifelsfrei zwischen Definitionsnamen und Event unterschieden werden kann.

'''Diese Funktion kann nur verwendet werden, wenn '''<code>$event_regexp</code>''' auf '''<code><Definitionsnamen></code>''' bzw. '''<code><Definitionsnamen>:<Event></code>''' matcht (Event Regexp-Syntax aus [[notify]]).'''

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Hash-Referenz der Definition, für welche eine neue Event-Regexp gesetzt wurde.
|-
| style="vertical-align:top" | '''<code>$event_regexp</code>'''

''mandatory''
|| Die Regexp, welche für <code>$hash</code> gesetzt wurde (i.d.R via [[DevelopmentModuleIntro#X_Define|Define-Funktion]])

|}

=== goodReadingName ===

<ul><syntaxhighlight lang="perl">
$valid = goodReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion goodReadingName() prüft, ob der Readingname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Readingname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>
* Bindestrich <code>-</code>
* Schrägstrich <code>/</code>

Sollte der Readingname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Readingname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Readingname zulässig ist.
Folgende Werte sind möglich:

0 - Readingname enthält unzulässige Zeichen 
1 - Readingname besteht aus zulässigen Zeichen
|}

=== makeReadingName ===

<ul><syntaxhighlight lang="perl">
$validName = makeReadingName($name);
</syntaxhighlight>
</ul>
Die Funktion makeReadingName() entfernt aus dem übergebenen Readingname <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Readingname in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Readingname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== zweistufige Modulkommunikation ==

=== AssignIoPort ===

<ul><syntaxhighlight lang="perl">
AssignIoPort($hash);
AssignIoPort($hash, $proposedName);
</syntaxhighlight></ul>

Die Funktion AssignIoPort() sucht nach einem passenden IO-Gerät (physikalische Definition) nach folgender Vorgehensweise:

# Sofern <code>$proposedName</code> angegeben ist und der Gerätename existiert und nicht disabled ist (Attribute <code>disable</code> auf 1 gesetzt), wird <code>$proposedName</code> als IO-Gerät ausgewählt.
# Sofern der Nutzer über das Attribut <code>IODev</code> einen Gerätenamen konfiguriert hat, wird dieser als IO-Gerät ausgewählt.
# Es werden alle Module geprüft, die entsprechende Nachrichten des Modultyps von <code>$hash</code> als IO-Gerät annehmen (via [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]]). Die passende Definition, welche als letztes definiert wurde, wird als IO-Gerät ausgewählt.

In den Fällen 1 und 2 wird keine Prüfung durchgeführt, ob das gewählte IO-Gerät überhaupt von dem eigenen Modul Daten verarbeiten kann. Im Fehlerfall wird beim Aufruf von [[#IOWrite|IOWrite()]] eine Fehlermeldung im Logfile erzeugt.

Das gefundene IO-Gerät wird mittels Hash-Referenz unter <code>$hash->{IODev}</code> gespeichert. Sollte kein passendes IO-Gerät gefunden werden, wird eine Meldung im Logfile produziert.

Generell sollte bei logischen Modulen die Funktion AssignIoPort() im Rahmen der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion aufgerufen werden, da sonst kein Senden von Daten via [[#IOWrite|IOWrite()]] möglich ist. Für den Empfang ist <code>$hash->{IODev}</code> ohne Bedeutung.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, für welche ein IO-Gerät zugewiesen werden soll.
|-
| style="vertical-align:top" | '''<code>$proposedName</code>'''

''optional''
| Der Gerätename, welcher als IO-Gerät verwendet werden soll. Übersteuert die interne Suche nach einem passenden Gerät. Sollte nur verwendet werden, wenn bei mehreren IO-Geräten die Kommunikation nur bspw. über das empfangene IO-Gerät durchgeführt werden kann.
|}

=== Dispatch ===

<ul><syntaxhighlight lang="perl">
$found = Dispatch($hash, $message);
$found = Dispatch($hash, $message, $additional_values, $no_unknown);
</syntaxhighlight></ul>

Die Funktion Dispatch() versucht die Nachricht <code>$message</code>, welche die Definition mit dem Hash <code>$hash</code> erhalten hat, an eine untergeordnete logische Definition weiterzureichen. Über diese Funktion werden Daten von einer physischen Definition an logische Definitionen verteilt. Optional können zur reinen Nachricht auch zusätzliche Daten in <code>$additional_values</code> mitgegeben werden (z.B. Empfangspegel, Signalqualität, ...). Diese Daten werden bei der gefundenen logischen Gerätedefinition als zusätzliche Internals gesetzt. Bei gesetzem Attribut <code>addvaltrigger</code> in der physischen Definition werden für diese Daten zusätzlich Events erzeugt (keine Readings!). Über das Flag <code>$no_unknown</code> kann man verhindern, dass für diese Nachricht im Falle einer nicht gefundenen logischen Gerätedefinition, ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt (und ggf. das zugehörige Modul nachgeladen) wird.

Die Funktion prüft dabei alle Module aus der [[DevelopmentModuleIntro#Die_Client-Liste|Client-Liste]], ob diese mit der Nachricht etwas anfangen können (via Match-Regexp), führt eine optionale Duplikatserkennung via [[DevelopmentModuleIntro#X_Fingerprint|Fingerprint]]-Funktion durch und gibt den Definitionsnamen zurück, welcher die Nachricht erfolgreich via [[DevelopmentModuleIntro#X_Parse|Parse]]-Funktion verarbeiten konnte (z.B. Erzeugen von Readings, Logmeldungen, usw.).

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche eine Nachricht an andere Module (bzw. deren Definitionen) weiterreichen möchte.
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
| Die Nachricht als Zeichenkette, welche durch ein anderes Modul verarbeitet werden soll. Hier sind nur Zeichenketten erlaubt, da die möglichen Empfängermodule über reguläre Ausdrücke die Nachricht prüfen.
|-
| style="vertical-align:top" | '''<code>$additional_values</code>'''

''optional can be <code>undef</code>''
| Zusätzliche Daten als Hash-Referenz, welche bei der gefundenen logischen Definition als Internals nach dem Schema <code><IO-Gerätname>_<Schlüssel>: <Wert></code> gesetzt werden. Dies kann bspw. der Empfangspegel (RSSI) oder die Rohnachricht sein.
|-
| style="vertical-align:top" | '''<code>$no_unknown</code>'''

''optional can be <code>undef</code>''
| Flag. Wenn gesetzt (Wert: <code>1</code>), wird kein zugehöriges Modul basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und kein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte die Nachricht <code>$message</code> nicht von bereits existierenden Definition verarbeitet werden können. Wenn dieses Flag den Wert <code>0</code> oder <code>undef</code> besitzt, wird ggf. das zugehörige Modul für die Nachricht basierend auf der [[DevelopmentModuleIntro#Die_Match-Liste|Match-Liste]] nachgeladen und ein entsprechendes [[DevelopmentModuleIntro#Automatisches_Anlegen_von_logischen_Ger.C3.A4tedefinitionen_.28autocreate.29|Event]] erzeugt, sollte keine passende Definition für diese Nachricht existieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$found </code>'''
| Eine Array-Referenz, welcher die gefundene Definition zu der Nachricht enthält. Wenn keine Definition gefunden wurde, wird <code>undef</code> zurückgegeben.
|}

=== IOWrite ===

<ul><syntaxhighlight lang="perl">
$ret = IOWrite($hash, @arguments);
</syntaxhighlight></ul>

Die Funktion IOWrite() übergibt die Daten <code>@arguments</code> der logischen Definition <code>$hash</code> an das ausgewählte IO-Gerät indem es die [[DevelopmentModuleIntro#X_Write|Write]]-Funktion mit den Daten <code>@arguments</code> aufruft. In <code>@arguments</code> ist üblicherweise eine Nachricht/Frame, sowie evtl. Zusatzdaten enthalten, welche das IO-Gerät nur noch an die verbundene Hardware übermitteln muss. Das kann ein einzelner Skalar mit der entsprechenden Nachricht sein, es können aber auch mehrere Werte übergeben werden. Die Aufrufsyntax muss dabei mit der [[DevelopmentModuleIntro#X_Write|Write]]-Funktion des entsprechenden physikalischen Moduls harmonieren.

Damit IOWrite() funktionieren kann, muss zunächst ein IO-Gerät mittels [[#AssignIoPort|AssignIoPort()]] zugewiesen werden. Dieser Aufruf wird üblicherweise in der [[DevelopmentModuleIntro#X_Define|Define]]-Funktion oder der [[DevelopmentModuleIntro#X_Notify|Notify]]-Funktion (Trigger auf <code>global:INITIALIZED</code> bzw. <code>global:REREADCFG</code>) durchgeführt. Erst nach dem Aufruf reicht IOWrite() die Daten an das entsprechende IO-Gerät weiter.

Der Inhalt von <code>$hash</code> wird nicht an die Write-Funktion übergeben. Sollte man <code>$hash</code> des logischen Gerätes auch im physikalischen Gerät benötigen, so kann man <code>$hash></code> mit in <code>@arguments</code> übergeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
| Die Hash-Referenz der Definition, welche Daten an ihr IO-Gerät übertragen möchte.
|-
| style="vertical-align:top" | '''<code>@arguments</code>'''

''mandatory''
| Die zu übertragenden Daten. Das Inhaltsschema muss dabei mit dem entgegennehmenden Modul harmonisieren.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>'''
| Der Rückgabewert der Write-Funktion des IO-Gerätes, welches die Daten verarbeitet hat.
|}

== Timer ==

=== InternalTimer===

<ul><syntaxhighlight lang="perl">InternalTimer($timestamp, $functionName, $arg);
InternalTimer($timestamp, $functionName, $arg, $waitIfInitNotDone);
</syntaxhighlight></ul>
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion <code>$functionName</code> wird dabei zum Zeitpunkt <code>$timestamp</code> mit dem Parameter <code>$arg</code> ausgeführt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>'''

''mandatory''
|| Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: <code>gettimeofday() + 30</code> um in 30 Sekunden etwas zu starten)
|-
| '''<code>$functionName</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
|-
| '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash, kann aber auch eine Zeichenkette oder jeder weitere Datentyp sein, der mit einem Skalar übergeben werden kann (kein direktes Array/Hash).
|-
| '''<code>$waitIfInitNotDone</code>'''

''optional''
||
'''ACHTUNG: Dieser Parameter sollte unter keinen Umständen verwendet werden!'''

Dieser Parameter verändert das Verhalten von InternalTimer() während der Initialisierung von FHEM. Ist dieser Parameter auf 1 gesetzt und FHEM noch in der Initialisierungsphase (Konfiguration einlesen), so wird ein Sleep des Hauptprozess durchgeführt, bis der gewünschte Zeitpunkt <code>$timestamp</code> erreicht ist. Dadurch wird der gesamte FHEM-Prozess solange blockiert und ist in dieser Zeit nicht ansprechbar. Dieses Verhalten ist besonders relevant bei der Nutzung von InternalTimer() in der [[DevelopmentModuleIntro#X_Define|Define-Funktion]] eines Moduls und sollte daher so keinesfalls benutzt werden. Um Funktionsaufrufe zu verzögern, bis die Initialisierung beendet ist, sollte auf das Event <code>global:INITIALIZED</code> in der [[DevelopmentModuleIntro#X_Notify|Notify-Funktion]] gewartet werden.

Standardwert: 0
|}

=== RemoveInternalTimer ===
<ul><syntaxhighlight lang="perl">RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $functionName);
</syntaxhighlight>
</ul>
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter <code>$arg</code> gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion <code>$functionName</code> weiter einschränken.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Der Übergabeparameter nach welchem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.
|-
| style="vertical-align:top" | '''<code>$functionName</code>'''

''optional''
|| Der Funktionsname der zusätzlich zu <code>$arg</code> gesucht werden soll.

|}

=== SetExtensionsCancel ===
<ul><syntaxhighlight lang="perl">SetExtensionsCancel($hash);
</syntaxhighlight>
</ul>
Die Funktion ''SetExtensionsCancel'' löscht möglicherweise noch anstehenden Timer, der durch ein ''on-for-timer'', ''off-for-timer'', ... über die ''SetExtensions'' angelegt wurde. Sollte in der [[DevelopmentModuleIntro#X_Set|SetFn]] aufgerufen werden, bevor der Devicezustand durch ein anderes Kommando geändert wird.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$hash</code>'''

''mandatory''
|| Die Hash-Referenz der Definition, durch die der Timer angelegt wurde.

|}

== Definitionen ==

=== devspec2array ===

<ul><syntaxhighlight lang="perl">
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash);
</syntaxhighlight>
</ul>
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification <code>$devspec</code> matchen.

Sollte keine Definition auf die übergebene Spezifikation passen, so wird <code>$devspec</code> als einziges zurückgegeben. Dieser Mechanismus ist aus historischen Gründen so gewählt um die Funktion devspec2array() transparent in Module einzufügen ohne große Änderungen im Code durchführen zu müssen. Daher ist es notwendig im Falle der Rückgabe eines einzelnen Elements dies nochmals auf Existenz in <code>%defs</code> zu prüfen.

Die genaue Syntax einer Device-Specification ist in der {{Link2CmdRef|Anker=devspec}} erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$devspec</code>'''

''mandatory''
|| Die Device-Specification zum Suchen nach Definitions-Namen.
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''optional''
|| Der Definitions-Hash der für den Aufruf verantwortlich ist. Dies dient zur Prüfung, ob diese Definition diesen Vorgang ausführen darf (Vorgangs-Typ: <code>devicename</code>).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>@list</code>''' || Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird <code>$devspec</code> unverändert zurückgegeben. Wenn <code>$client_hash</code> gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird <code>""</code> (Leerstring) zurückgegeben.
|}

=== goodDeviceName ===

<ul><syntaxhighlight lang="perl">
$valid = goodDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion goodDeviceName() prüft, ob der Definitionsname <code>$name</code> ein gültiger Bezeichner innerhalb von FHEM ist. Ein gültiger Definitionsname besteht aus folgenden Zeichen bzw. Zeichengruppen:

* Normale Buchstaben ohne deutsche Sonderzeichen (A-Z, groß/klein)
* Zahlen (0-9)
* Punkt <code>.</code>
* Unterstrich <code>_</code>

Sollte der Definitionsname gültig sein, gibt die Funktion als Rückgabewert <code>1</code> zurück, andernfalls <code>0</code>. Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Definitionsname aus gültigen Zeichen besteht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$return</code>''' || Wahrheitswert, ob der übergebene Definitionsname zulässig ist.
Folgende Werte sind möglich:

0 - Definitionsname enthält unzulässige Zeichen 
1 - Definitionsname besteht aus zulässigen Zeichen
|}

=== makeDeviceName ===

<ul><syntaxhighlight lang="perl">
$validName = makeDeviceName($name);
</syntaxhighlight>
</ul>
Die Funktion makeDeviceName() entfernt aus dem übergebenen Definitionsnamen <code>$name</code> alle ungültigen Zeichen und ersetzt diese durch einen Unterstrich "_". Als Rückgabewert erhält man nun einen konformen Definitionsnamen in dem nur noch erlaubte Zeichen (Buchstaben, Zahlen, Punkt sowie Unterstrich) enthalten sind.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, welcher geprüft werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$validName</code>''' || Der modifizierte Name, welcher übergeben wurde, ohne ungültige Zeichen. Alle evtl. ungültigen Zeichen sind durch einen Unterstrich ersetzt.
|}

== Daten abfragen/auslesen ==

=== ReadingsVal ===

:<syntaxhighlight lang="perl">
$value = ReadingsVal($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings welcher ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== ReadingsTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = ReadingsTimestamp($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

=== ReadingsAge===

:<syntaxhighlight lang="perl">
$seconds = ReadingsAge($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings <code>$reading</code> der Definition <code>$name</code> zurück. Es handelt sich hierbei um den Zeitpunkt an dem das Reading zuletzt gesetzt/aktualisiert wurde. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll.
|-
| '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll.
|-
| '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$seconds</code>''' || Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind
|}

=== ReadingsNum ===

:<syntaxhighlight lang="perl">
$number = ReadingsNum($name, $reading, $default);
</syntaxhighlight>
Die Funktion ReadingsNum() extrahiert einen numerischen Wert aus dem Reading <code>$reading</code> der Definition <code>$name</code> und gibt diesen zurück. Dabei werden Zeichenketten wie z.B. Einheiten eliminiert und nur die eigentliche Zahl (Ganzzahl- oder Fließkommazahl) zurückgegeben. Sollte das gewünschte Reading nicht existieren, wird <code>$default</code> zurückgegeben. Sollte das gewünschte Reading existieren, jedoch keinen numerischen Wert enthalten, wird ebenfalls <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$reading</code>'''

''mandatory''
|| Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert, bzw. keinen numerischen Wert enthält.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$number</code>''' || Numerischer Wert des gewünschten Readings oder <code>$default</code>, wenn es nicht existiert.
|}

=== AttrVal ===

:<syntaxhighlight lang="perl">
$value = AttrVal($name, $attribute, $default);
</syntaxhighlight>
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut <code>$attribute</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Attribut ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$attribute</code>'''

''mandatory''
|| Der Name des Attributs, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert.
|-
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Attributs oder <code>$default</code>, wenn es nicht existiert.
|}

=== InternalVal ===

:<syntaxhighlight lang="perl">
$value = InternalVal($name, $internal, $default);
</syntaxhighlight>
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals <code>$internal</code> der Definition <code>$name</code> zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird <code>$default</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem das gewünschte Internal ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$internal</code>'''

''mandatory''
|| Der Name des Internals, dessen Wert ausgelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$default</code>'''

''mandatory can be <code>undef</code>''
|| Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Inhalt des gewünschten Internal oder <code>$default</code>, wenn es nicht existiert.
|}

=== Value===

:<syntaxhighlight lang="perl">
$value = Value($name);
</syntaxhighlight>
Die Funktion Value() gibt den aktuellen Status von Definition <code>$name</code> zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Status der gewünschten Definition
|}

=== OldValue===

:<syntaxhighlight lang="perl">
$value = OldValue($name);
</syntaxhighlight>
Die Funktion OldValue() gibt den Status der Definition <code>$name</code> zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>''' || vorheriger Status der gewünschten Definition
|}

=== OldTimestamp===

:<syntaxhighlight lang="perl">
$timestamp = OldTimestamp($name);
</syntaxhighlight>
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition <code>$name</code> als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird <code>""</code> (Leerstring) zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name aus dem der Status ausgelesen werden soll.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$timestamp</code>''' || Zeitstempel in lokaler Zeitzone im Format
<code>2016-02-16 19:34:24</code>
|}

== Attribute in anderen Definitionen bereitstellen ==

=== addToAttrList===
:<syntaxhighlight lang="perl">
addToAttrList($attrib);
</syntaxhighlight>
Die Funktion addToAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>global</code> hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll.
|}

=== addToDevAttrList ===

:<syntaxhighlight lang="perl">
addToDevAttrList($name, $attrib);
</syntaxhighlight>
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen <code>$attrib</code> zu dem Attribut <code>userattr</code> der Definition <code>$name</code> hinzu. Damit kann dieses Attribut in der Definition <code>$name</code> verwendet und gesetzt werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll.
|-
| style="vertical-align:top" | '''<code>$attrib</code>'''

''mandatory''
|| Der Name des Attributs, welches für die Definition <code>$name</code> verfügbar gemacht werden soll.
|}

== Daten dauerhaft schreiben/lesen ==

=== FileRead ===

<ul><syntaxhighlight lang="perl">
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param);
</syntaxhighlight>
</ul>
Die Funktion FileRead() liest den Inhalt der Datei <code>$filename</code> ein und gibt diesen als ein zeilenweises Array zurück. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelesen. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die eingelesen werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code> oder <code>""</code> (Leerstring).
|-
| style="vertical-align:top" | '''<code>@content</code>''' || Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert <code>undef</code>
|}

=== FileDelete ===

<ul><syntaxhighlight lang="perl">
$error = FileDelete($filename);
$error = FileDelete($param);
</syntaxhighlight>
</ul>
Die Funktion FileDelete() löscht die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig aus der Datenbank gelöscht. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert das Löschen der Datei im Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei die gelöscht werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file" }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Löschen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Löschvorgang erfolgreich, enthält <code>$error</code> den Wert <code>undef</code>.
|}

=== FileWrite ===

<ul><syntaxhighlight lang="perl">
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content);
</syntaxhighlight></ul>
Die Funktion FileWrite() schreibt den übergebenen Inhalt <code>@content</code> in die Datei <code>$filename</code>. In Verwendung mit configDB wird die Datei standardmäßig in die Datenbank geschrieben. Um im Falle von configDB dennoch auf das Dateisystem zugreifen zu können muss als Übergabeparameter ein Hash <code>$param</code> gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$filename</code>'''

''mandatory''
|| Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wie folgt übergeben werden:
<code>{ FileName => $filename, ForceType => "file", NoNL => 0 }</code>

Die Variable <code>$filename</code> enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert <code>NoNL</code> auf 1 setzen um kein Newline (<code>\n</code>) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.
|-
| style="vertical-align:top" | '''<code>@content</code>'''

''mandatory''
|| Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile).
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== setKeyValue ===

:<syntaxhighlight lang="perl">$error = setKeyValue($key, $value)</syntaxhighlight>
Die Funktion setKeyValue() speichert die Daten <code>$value</code> unter dem Schlüssel <code>$key</code> ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einem Neustart von FHEM verfügbar. Die Daten welche in <code>$value</code> enthalten sind, dürfen dabei keine Zeilenumbrüche enthalten. Sollten Daten mit Zeilenumbrüchen auf diese Weise gespeichert werden, so müssen Zeilenumbrüche durch entsprechende Mechanismen (z.B. Base64 oder das Ersetzen durch alternative Trennzeichen) eliminiert werden.

'''ACHTUNG:''' Die Daten werden im Klartext in einer Datei auf dem Dateisystem abgelegt! Sensible Daten die mit setKeyValue gespeichert werden (z.B. Passwörter, Zugangsdaten, etc.) sollten durch entsprechende Mechanismen (z.B. Verschlüsselung) unleserlich gemacht werden.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten abgespeichert werden soll (bspw. Definitions-Namen). Der Schlüssel darf dabei keine Zeilenumbrüche enthalten.
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.

Wenn <code>$value</code> den Wert <code>undef</code> besitzt, werden zuvor gespeicherte Daten gelöscht.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|}

=== getKeyValue ===

:<syntaxhighlight lang="perl">($error, $value) = getKeyValue($key)</syntaxhighlight>
Die Funktion getKeyValue() gibt Daten, welche zuvor per <code>setKeyValue()</code> gespeichert wurden, zurück.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$key</code>'''

''mandatory''
|| Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden.
|}

Rückgabewert:
{| class="wikitable"
|-
! Rückgabe!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$error</code>''' || Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält <code>$error</code> den Wert <code>undef</code>
|-
| style="vertical-align:top" | '''<code>$value</code>''' || Die Daten, welche unter dem gegebenen Schlüssel <code>$key</code> hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt <code>$value</code> den Wert <code>undef</code>
|}

== Logging ==

=== Log ===

<syntaxhighlight lang="perl">
Log($verbose, $message);
</syntaxhighlight>
Die Funktion Log() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem globalen Attribut <code>verbose</code> ist. Wenn <code>$verbose</code> größer ist als das globale Attribut <code>verbose</code>, wird die Meldung nicht geloggt.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Log3 ===

<syntaxhighlight lang="perl">
Log3($name, $verbose, $message);
</syntaxhighlight>
Die Funktion Log3() schreibt die Meldung <code>$message</code> in das FHEM-Logfile, sofern <code>$verbose</code> kleiner gleich dem Attribut <code>verbose</code> der Definition <code>$name</code> ist. Wenn das Attribut <code>verbose</code> in der Definition <code>$name</code> nicht gesetzt ist, wird gegen das globale Attribut <code>verbose</code> geprüft.

Diese Funktion ist primär für die Log-Ausgabe in Modulen gedacht um so dem User die Möglichkeit zu geben nur für bestimmte Definitionen den Verbose-Level zu erhöhen ohne den globalen Verbose-Level zu erhöhen.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory can be <code>undef</code>''
|| Der Name der Definition wogegen geprüft werden soll. Wenn <code>$name</code> in FHEM nicht existiert, oder den Wert <code>undef</code> besitzt, wird der Parameter <code>$verbose</code> gegen das globale Attribut <code>verbose</code> geprüft.
|-
| style="vertical-align:top" | '''<code>$verbose</code>'''

''mandatory''
|| Der Verbose-Level unter dem die Nachricht <code>$message</code> geloggt werden soll.

Ganzzahl zwischen 0 und 5
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

=== Debug ===

<syntaxhighlight lang="perl">
Debug($message);
</syntaxhighlight>
Die Funktion Debug() schreibt die Meldung <code>$message</code> mit dem Präfix <code>DEBUG></code> in das FHEM-Logfile. Diese Funktion ist zum temporären Debuggen gedacht und sollte nicht fest in einem Modul verwendet werden. Sie entspricht dem Aufruf:
<syntaxhighlight lang="perl">
Log(1, "DEBUG>".$message);
</syntaxhighlight>

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$message</code>'''

''mandatory''
|| Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.
|}

== Status-Abfragen ==
=== IsDevice ===

:<syntaxhighlight lang="perl">
$status = IsDevice($name);
$status = IsDevice($name, $type);
</syntaxhighlight>
Die Funktion IsDevice() prüft, ob die Definition <code>$name</code> existiert. Optional kann man prüfen, ob die Definition <code>$name</code> dem Modultyp <code>$type</code> entspricht.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition existiert, bzw. einem bestimmten Modultyp entspricht.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher auf Vorhandensein geprüft werden soll.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''optional''
|| Ein regulärer Ausdruck der gegen den Modulnamen (<code>$hash->{TYPE}</code>) der Definition <code>$name</code> geprüft werden soll. Dieser Ausdruck muss auf den gesamten Modulnamen passen, da der Ausdruck mit <code>^</code> und <code>$</code> umschlossen wird.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Das Ergebnis, ob eine solche Definition existiert:

0 - Definition existiert nicht 
1 - Definition existiert 

Wenn nur <code>$name</code> übergeben ist, wird nur geprüft ob eine Definition mit diesem Namen existiert. Wenn zusätzlich <code>$type</code> parametrisiert wurde, muss eine Definition mit dem Namen <code>$name</code> existieren '''UND''' dem Modultypen <code>$type</code> entsprechen.
|}

=== IsDisabled ===

:<syntaxhighlight lang="perl">
$status = IsDisabled($name);
</syntaxhighlight>
Die Funktion IsDisabled() prüft, ob die Definition <code>$name</code> aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: <code>inactive</code>). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer <code>0</code> zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert <code>0</code> zurück.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist durch das Attribut <code>disable</code> deaktiviert 
2 - Definition ist durch das Attribut <code>disabledForIntervals</code> deaktiviert 
3 - Definition ist durch den User inaktiv geschaltet. Dies bedeutet <code>$hash->{STATE}</code> oder das Reading <code>state</code> der Definition besitzt den Wert <code>inactive</code>.
|}

=== IsDummy ===

:<syntaxhighlight lang="perl">
$status = IsDummy($name);
</syntaxhighlight>
Die Funktion IsDummy() prüft, ob die Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition ist im Dummy-Modus 
|}

=== IsIgnored ===

:<syntaxhighlight lang="perl">
$status = IsIgnored($name);
</syntaxhighlight>
Die Funktion IsIgnored() prüft, ob die Definition <code>$name</code> durch den User ignoriert wird (Attribut: <code>ignore</code>). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name welcher geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status der Definition. Je nach Status sind folgende Werte möglich:

0 - Definition ist aktiv 
1 - Definition wird ignoriert 
|}

=== IsIoDummy ===

:<syntaxhighlight lang="perl">
$status = IsIoDummy($name);
</syntaxhighlight>
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition <code>$name</code> in den Dummy-Modus versetzt wurde (Attribut: <code>dummy</code>). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert <code>1</code> zurück, andernfalls <code>0</code>.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein IO-Device einer Definition im Dummy-Modus ist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitions-Name, dessen IO-Device geprüft werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:

0 - IO-Device der Definition ist aktiv 
1 - IO-Device der Definition ist im Dummy-Modus 
|}

== Sicherheit ==

=== Authenticate ===

:<syntaxhighlight lang="perl">
$result = Authenticate($client, $argument);
</syntaxhighlight>

TBD

=== Authorized ===

:<syntaxhighlight lang="perl">
$result = Authorized($client_hash, $type, $arg);
</syntaxhighlight>

Die Funktion Authorized() prüft, ob ein Client mit dem Client-Hash <code>$client_hash</code> die Aktion <code>$type</code>/<code>$arg</code> ausführen darf bzw. dazu berechtigt ist. Dazu werden sämtliche Definitionen in FHEM befragt, deren Module die Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereitstellen. Die beiden Argumente <code>$type</code>/<code>$arg</code> werden dabei 1:1 an die [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion der jeweiligen Module übergeben.

Nachdem alle Definitionen zu dem jeweiligen Vorgang befragt wurden, gibt die Funktion zurück, ob der Client dazu authorisiert ist. Sobald eine Definition den Vorgang explizit verbietet, wird sofort der Rückgabewert <code>0</code> zurückgegeben. Wenn eine Definition den Vorgang explizit erlaubt, wird sofort der Wert <code>1</code> zurückgegeben. In beiden Fällen werden weitere Definitionen nicht mehr befragt. Sollte keine Definition den Vorgang explizit erlauben/verbieten oder keine Definition zum Prüfen vorhanden sein, wird die Aktion generell erlaubt durch die Rückgabe von <code>1</code>. Sollte ebenfalls keine Bewertung möglich sein aufgrund eines fehlenden oder unvollständigen Client-Hash, wird der Vorgang generell erlaubt.

Innerhalb von FHEM werden zwei Vorgangstypen bereits verwendet um die Befehlsausführung und Sichtbarkeit von Definitionen in FHEM einzuschränken. Das Modul [[allowed]] stellt dabei die entsprechende Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]] bereit.

Die Funktion Authorized() ist daher nur notwendig, wenn man weiterführende Beschränkungen für einzelne Clients in Modulen/Definitionen realisieren möchte, die über die bestehenden Möglichkeiten hinausgehen. Dazu muss natürlich ein entsprechendes Gegenstück in Form eines weiteren Moduls zur Verfügung stehen, welche diese neuen Vorgangstypen entsprechend bewerten kann.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob ein Client zu einem bestimmten Vorgang authorisiert ist.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$client_hash</code>'''

''mandatory''
|| Der Client-Hash, welcher einen Vorgang durchführen möchte.
|-
| style="vertical-align:top" | '''<code>$type</code>'''

''mandatory''
|| Der Vorgangstyp als Zeichenkette, um welchen es geht. Innerhalb von fhem.pl werden aktuell zwei Typen unterschieden: 
* <code>cmd</code> - Befehlsausführung (sowohl FHEM-Befehle als auch Shell-/Perl-Aufrufe)
* <code>devicename</code> - Sichtbarkeit von Definitionen innerhalb von FHEM

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|-
| style="vertical-align:top" | '''<code>$arg</code>'''

''mandatory''
|| Ein zusätzliches Argument um den jeweiligen Vorgangstyp genauer zu beschreiben. Eine Beschreibung der Bedeutung von <code>$arg</code> in Verbindung mit den bereits vorhandenen Vorgangstypen (<code>cmd</code>/<code>devicename</code>) gibt es in der Beschreibung von <code>$arg</code> zur Modulfunktion [[DevelopmentModuleIntro#X_Authorize|X_Authorize()]]

Generell können hier weitere Typ/Argument-Kombinationen verwendet werden, solange es ein korrespondierendes Modul mit [[DevelopmentModuleIntro#X_Authorize|Authorize]]-Funktion gibt, welches diese Vorgänge verarbeiten kann.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$result</code>'''
|| Ergebnis, ob der zu prüfende Vorgang authorisiert ist.

* <code>0</code> - Vorgang ist NICHT authorisiert und darf nicht ausgeführt werden.
* <code>1</code> - Vorgang ist authorisiert.
|}

== Modulfunktionen ausführen ==

=== CallFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallFn($name, $function_name, @args);
@ret = CallFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallFn() ruft von der Definition <code>$name</code> die im Modul registrierte Funktion <code>$function_name</code> mit den Argumenten <code>@args</code> auf und gibt das Ergebnis dieses Funktionsaufrufs zurück. Dazu wird die Funktion im entsprechenden Modul-Hash des zugrunde liegenden Moduls von <code>$name</code> gesucht. Entsprechende Funktionen werden im Rahmen der [[DevelopmentModuleIntro#X_Initialize|Initialize]]-Funktion beim Laden eines Moduls registriert.

Bei einem erfolgreichen Aufruf gibt CallFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte das zugrunde liegende Modul die entsprechende Funktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modulfunktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]] im Modul-Hash registriert wurde.

Bsp:
* <code>"SetFn"</code>
* <code>"DbLog_splitFn"</code>
* <code>"CopyFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

=== CallInstanceFn ===

<ul><syntaxhighlight lang="perl">
$ret = CallInstanceFn($name, $function_name, @args);
@ret = CallInstanceFn($name, $function_name, @args);
</syntaxhighlight></ul>
Die Funktion CallInstanceFn() ist eine Erweiterung zu [[#CallFn|CallFn()]]. Die auszuführende Funktion <code>$function_name</code> wird dabei zuerst in dem Definitions-Hash von <code>$name</code> gesucht. Der Funktionsname muss dabei direkt in <code>$hash</code> definiert sein (ähnlich wie beim Modul-Hash im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]]). Der Funktionsname kann in <code>$hash</code> dabei optional mit einem Punkt als Präfix vorangestellt sein um eine Anzeige in FHEMWEB zu unterbinden. Sollte die Funktion <code>$function_name</code> innerhalb des Definitions-Hash von <code>$name</code> nicht existieren, wird [[#CallFn|CallFn()]] mit den gleichen Parametern aufgerufen um die Funktion im zugrunde liegenden Modul aufzurufen, sofern diese ebenfalls existiert.

Dadurch kann man eine registrierte Modulfunktion definitionsbezogen in Einzelfällen übersteuern durch bspw. äquivalente Modulfunktionen aus Hilfsmodulen.

Bei einem erfolgreichen Aufruf gibt CallInstanceFn() den/die Rückgabewert/-e der Modulfunktion zurück. Sollte sowohl die Definition, als auch das zugrunde liegende Modul die entsprechende Modulfunktion nicht bereitstellen, wird <code>undef</code> zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Name der Definition, für den ein Aufruf einer Modul-Funktion durchgeführt werden soll.
|-
| style="vertical-align:top" | '''<code>$function_name</code>'''

''mandatory''
|| Der Name der Funktion als Zeichenkette, welche aufgerufen werden soll. Dieser Wert entspricht dem Schlüsselwort mit dem die entsprechende Funktion in <code>$hash</code> und, im Rahmen von [[DevelopmentModuleIntro#X_Initialize|X_Initialize()]], im Modul-Hash registriert wurde.

Bsp:
* <code>"DbLog_splitFn"</code>
|-
| style="vertical-align:top" | '''<code>@args</code>'''

''mandatory''
|| Eines oder mehrere Argumente, welche beim Aufruf der Modulfunktion entsprechend mitgegeben werden sollen. Die Argumente sind hier je nach Modulfunktion unterschiedlich. Die Aufrufsyntax und deren Reihenfolge muss in Modulen, welche die entsprechende Modulfunktion unterstützen in gleicher Art und Weise implementiert werden.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$ret</code>''' / '''<code>@ret</code>''' || Der Rückgabewert der Modulfunktion als Skalar oder Array (je nach Kontext).

Sollte die gewünschte Funktion in der Definition, als auch im zugrunde liegenden Modul nicht existieren, wird nur <code>undef</code> zurückgegeben.
|}

== Sonstiges ==

=== configDBUsed ===

:<syntaxhighlight lang="perl">
$status = configDBUsed();
</syntaxhighlight>
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert <code>1</code> zurück. Die Funktion besitzt keinerlei Übergabeparameter.

Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob configDB verwendet wird.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$status</code>''' || Folgende Werte sind möglich: 

0 - configDB wird nicht verwendet 
1 - configDB wird verwendet
|}

=== getUniqueId ===

:<syntaxhighlight lang="perl">
$uniqueID = getUniqueId();
</syntaxhighlight>
Die Funktion getUniqueId() gibt einen eindeutige Identifikations-String der lokalen FHEM-Installation zurück. Dieser String wird einmalig per Zufallsalgorithmus erzeugt und anschließend lokal abgespeichert. Jede FHEM-Installation besitzt einen anderen Identifikations-String. Dieser Wert wird bspw. für die Online-Statistik verwendet um die einzelnen Installation zu anonymisieren.

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$uniqueID</code>''' || Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist.
|}

=== toJSON ===

:<syntaxhighlight lang="perl">
$jsonString = toJSON($value);
</syntaxhighlight>
Die Funktion toJSON() konvertiert eine komplexe Datenstruktur, welche aus Array, Hashes oder Skalaren bestehen kann, in einen JSON-konformen String. Als Argument <code>$value</code> kann man daher eine Array-Referenz, eine Hash-Referenz oder einen einfachen, skalaren Wert übergeben. Als Rückgabewert wird ein JSON-konformer String zurückgegeben.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$value</code>'''

''mandatory can be <code>undef</code>''
|| Eine Array-Referenz, eine Hash-Referenz oder ein einfacher, skalarer Wert, welcher in JSON zurückgeben werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$jsonString </code>''' || Der JSON-String, welcher das Objekt samt Inhalt darstellt.
|}

=== CancelDelayedShutdown ===

:<syntaxhighlight lang="perl">
CancelDelayedShutdown($name);
</syntaxhighlight>
Die Funktion CancelDelayedShutdown() ist nur im Zusammenhang mit einer im Modul implementierten [[DevelopmentModuleIntro#X_DelayedShutdown|DelayedShutdown]]-Funktion notwendig. Sofern über die DelayedShutdown-Funktion ein verzögertes Herunterfahren von FHEM signalisiert wird, dient CancelDelayedShutdown() dazu FHEM zu signalisieren, dass alle notwendigen Schritte vor dem Herunterfahren für die Definition <code>$name</code> abgeschlossen sind und FHEM sich nun beenden kann.

Parameter:
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$name</code>'''

''mandatory''
|| Der Definitionsname, für den die Shutdown-Verzögerung abgebrochen werden soll
|}

[[Kategorie:Development]]

Event-on-update-reading

2021-02-03T20:13:58Z

ChristophMorrison: Typos, Klarstellung

{{SEITENTITEL:event-on-update-reading}} 

Mit dem Attribut [[event-on-update-reading]] kann für Readings eines Gerätes festgelegt werden, dass bei jeder Aktualisierung ein Event (und damit in der Regel auch ein Log-Eintrag) erzeugt werden soll. Da dies das Defaultverhalten von FHEM ist, ist event-on-update-reading nur dann sinnvoll einsetzbar, wenn das Defaultverhalten vorher mit dem Attribut [[event-on-change-reading]] eingeschränkt wurde.

Wird ''event-on-update-reading'' für ein einzelnes Reading gesetzt, werden zunächst alle übrigen Readings nicht mehr protokolliert, erzeugen also keine Events mehr.
== Einführung ==
FHEM erzeugt für jedes gemeldete Reading ein Event, egal, ob das Reading sich geändert hat, oder nur Intervallweise per Update aktualisiert wurde. Dieses Verhalten kann Nachteile haben und daher mit [[event-on-change-reading]] für ein Gerät abgestellt werden.

[[event-on-update-reading]] dient dazu, für '''einzelne''' Readings des Gerätes das Standardverhalten wieder herzustellen, sollte es für bestimmte Readings in einer gegeben FHEM Installation sinnvoll sein, doch bei jedem Update auch ohne Werteänderung ein Event zu erhalten. Dies kann z.b. bei der Erzeugung von Graphen notwendig sein.
== Syntax ==
Das ''event-on-update-reading'' Attribut wird in der folgenden Weise spezifiziert:
:<code><nowiki>attr <device> event-on-update-reading reading1[,reading2...n]</nowiki></code>
Die zu berücksichtigenden Readings sind als durch Kommata getrennte Werte anzugeben, können aber auch über reguläre Ausdrücke zusammengefasst werden.

== Wechselwirkungen ==
Dieses Attribut steht in Wechselwirkung mit den Attributen [[event-on-change-reading]] und [[event-min-interval]], bitte beim Einsatz berücksichtigen. Ein Einsatz ohne gleichzeitige event-on-change-reading ist idR. nicht sinvoll.

Sind bei einem Device weder ''event-on-update-reading'' noch ''event-on-change-reading'' spezifiziert, werden für alle Readings sowohl bei Aktualisierung (mit dem gleichen Wert) als auch bei der Änderung Events erzeugt, dies ist das Standardverhalten. Sobald jedoch eines der beiden Attribute gesetzt ist, müssen alle Readings, die protokolliert werden sollen bei (mindestens) einem der Attribute berücksichtigt sein.

Ist für ein Reading sowohl ''event-on-change-reading'' als auch ''event-on-update-reading'' spezifiziert, wird bei jeder Aktualisierung des Readings ein Event erzeugt, das ''event-on-change'' wird für dieses Reading also außer Kraft gesetzt bzw. "überschrieben".

== Beispiele ==
Hat man durch
:<code>attr <device> event-on-change-reading .*</code>
erreicht, dass alle Readings des Gerätes nur noch bei Werteänderung eine Event erzeugen (und somit auch nur dann geloggt werden), kann mit
:<code><nowiki>attr <device> event-on-update-reading temperature, humidity</nowiki></code>
dafür gesorgt werden, das für Temperatur und Luftfeuchte dennoch mit jedem Update (intervallweise Aktualisierung auch ohne Werteänderung) ein Event erzeugt und geloggt wird.

== Praktische Anwendung ==
Da mit [[event-min-interval]] ebenfalls dafür gesorgt werden kann, dass Readings auch ohne Werteänderungen ein Event erzeugen, muss beim Einsatz geprüft werden, ob event-min-interval nicht sinnvoller als event-on-update-reading ist. Da die Updateintervalle einiger Geräte recht kurz sind, kann der Einsatz event-on-update-reading immer noch sehr viele (ggf. nutzlose) Events für das gegebene Reading erzeugen.

== Siehe auch ==
*[[event-on-change-reading]]
*[[event-min-interval]]

== Links ==
* Benutzungstipps (''Best Practice'') für das Attribut in {{Link2Forum|Topic=36522|LinkText=diesem Forenthread}}

[[Kategorie:Attribut (allgemeingültig)]]

CPAN

2020-11-16T09:19:29Z

ChristophMorrison: RPM-Sektion eingefügt

= CPAN =

Das CPAN, Comprehensive Perl Archive Network, ist ein weltweit verteiltes Netzwerk für Perl-Module, das seit 1995 besteht und aktuell etwa 200 000 Module umfasst.

Siehe auch hier eine [https://www.cpan.org/modules/INSTALL.html Zusammenfassung des CPAN-Projektes].

== Clients ==

=== Plattformunabhängig ===

Das CPAN bietet drei plattformunabhängige Clients an, von denen zwei hier beschrieben werden. Die ''Empfehlung'' ist, <code>cpanm</code> zu nutzen.

==== cpanminus ====

[https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm cpanminus] (<code>cpanm</code>) ist der bevorzugte Weg, wie CPAN-Pakete installiert werden sollten. cpan-minus ist, wie <code>cpan</code> ein CPAN-Paket, das aber auch für viele Betriebssystem als fertiges Paket portiert wurde.

cpan-minus bietet einen [http://cpanmin.us/ Quickstart] an, der auf jedem System läuft, auf dem Perl installiert ist. Dazu muss folgender Befehl auf der Kommandozeile ausgeführt werden:

<pre>curl -L https://cpanmin.us | perl - App::cpanminus</pre>
Aus Sicherheitsgründen sollte vor Ausführung des Befehls überprüft werden, was unter [http://cpanmin.us/ cpanmin.us] zu finden ist, da ggf. Schadcode unbemerkt eingeschmuggelt werden könnte.

Ist der Client <code>cpanm</code> installiert, kann mit

<pre>cpanm Paket::Name</pre>
ein Paket (in diesem Falle das nicht-existende Paket <code>Paket::Name</code>) installiert werden. Die Option <code>--sudo</code> sorgt dafür, dass cpanminus die Installation als Superuser versucht (ggf. muss ein Passwort eingegeben werden).

==== Exkurs: cpan-outdated ====

Das Paket [https://metacpan.org/pod/distribution/cpan-outdated/script/cpan-outdated <code>cpan-outdated</code>] erzeugt eine cpanminus-kompatible Liste an CPAN-Paketen, die aktualisiert werden können, z.B.

<pre>$ cpan-outdated
A/AN/ANDK/CPAN-2.27.tar.gz
L/LE/LEONT/Test-Harness-3.42.tar.gz
B/BI/BINGOS/Archive-Tar-2.36.tar.gz
T/TO/TODDR/autodie-2.32.tar.gz
R/RU/RURBAN/B-Debug-1.26.tar.gz
I/IL/ILMARI/bareword-filehandles-0.007.tar.gz
P/PJ/PJACKLAM/bignum-0.51.tar.gz
X/XS/XSAWYERX/Carp-1.50.tar.gz
L/LE/LEEJO/CGI-4.47.tar.gz
A/AT/ATOOMIC/Clone-0.45.tar.gz
M/ML/MLEHMANN/common-sense-3.75.tar.gz
P/PM/PMQS/Compress-Raw-Bzip2-2.093.tar.gz
P/PM/PMQS/Compress-Raw-Zlib-2.093.tar.gz
P/PM/PMQS/IO-Compress-2.093.tar.gz
H/HM/HMBRAND/Config-Perl-V-0.31.tgz
A/AT/ATOOMIC/TimeDate-2.33.tar.gz
P/PM/PMQS/DB_File-1.853.tar.gz
H/HU/HURRICUP/Devel-Camelcadedb-v2019.1.tar.gz
P/PJ/PJCJ/Devel-Cover-1.36.tar.gz
A/AT/ATOOMIC/Devel-PPPort-3.58.tar.gz
M/MS/MSHELOR/Digest-SHA-6.02.tar.gz
R/RJ/RJBS/Email-Sender-1.300034.tar.gz</pre>
Sehr nützlich ist die Kombination aus cpanminus und cpan-outdated:

<pre>cpan-outdated | cpanm --sudo</pre>
Diese Befehlssequenz aktualisiert alle aktualisierbaren CPAN-Pakete mit Hilfe von cpanminus (als Superuser).

==== cpan ====

[https://metacpan.org/pod/CPAN <code>cpan</code>] ist der mit jeder Perl-Installation mitgelieferte Client für das CPAN und lässt sich entweder mit

<pre>perl -MCPAN -e shell</pre>
oder

<pre>cpan</pre>
starten. Es wird ein interaktiver Client gestartet; mit <code>h</code> kann eine sehr umfangreiche Hilfe aufgerufen werden.

Ein Modul lässt sich am einfachsten mit

<pre>cpan install PAKET::NAME</pre>
installieren (hier das nicht-existente Paket <code>PAKET::NAME</code>). <code>cpan</code> eignet sich weniger gut um Module zu installieren oder zu aktualisieren, aber sehr gut um nach Paketen zu suchen:

<pre>i /JSON/</pre>
findet jedes Paket, das die Zeichenkette <code>JSON</code> im Bereich Autor, Bundle, Distribution oder Modul enthält. Das sind meist viele Ergebnisse, aber liefert einen Überblick "was geht".

Erfahrungsgemäß ist <code>cpan</code> recht störrisch in der Handhabung. Deshalb empfehle ich die Nutzung von cpanminus.

=== OS-Paketmanager ===

==== Debian und Derivate (Ubuntu, Raspbian, etc.) ====

Vom Debian-Projekt werden viele, aber lange nicht alle, Pakete des CPAN auch als Pakete für den eingebauten Paketmanager <code>apt</code> [https://packages.debian.org/stable/perl/ bereitsgestellt]. Dort sind momentan etwa 4 000 Pakete verfügbar, d.h. rund 2% der im CPAN verfügbaren Pakete. Es ist nicht immer trivial, ein Paket zu finden. Ein einfacher Fall ist z.B. das Paket <code>Readonly</code>, das über <code>cpanm Readonly</code> oder <code>apt-get install libreadonly-perl</code> installiert werden könnte. Im Allgemeinen kann man sagen, dass sich der Name des <code>apt</code>-Paketes aus dem Prefix <code>lib</code>, gefolgt vom Paketnamen in Kleinbuchstaben, bei dem die <code>::</code> durch <code>-</code> ersetzt wurden, und dem Suffix <code>-perl</code> zusammensetzt:

{|
! CPAN
! Debian-Paket
|-
| Rose::URI
| librose-uri-perl
|-
| Sah::Schemas::Rinci
| libsah-schemas-rinci-perl
|}

Kein Beispiel wäre vollständig ohne Ausnahme, z.B.:

[https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>libromana-perligata-perl</code>] installiert das Perl-Paket [https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>Lingua::Romana::Perligata</code>], müsste nach der selbstgewählten Konvention aber <code>liblingua-romana-perligata-perl</code> heißen.

Vorteilhaft ist, dass man die Pakete zusammen mit anderen Debian-Paketen automatisch auf dem aktuellen Stand halten kann, z.B. [https://wiki.debian.org/UnattendedUpgrades <code>unattended-upgrades</code>] - man spart so eine doppelte Implementierung der Updates.

Wiederum von Nachteil ist, dass man mit einer auf ein Release festgelegten Quelle irgendwann auch keine Updates der Perl-Pakete mehr erhält.

==== SuSE Linux ====

YaST bietet aktuell etwa 3 121 der rund 200 000 Pakete in [https://build.opensuse.org/project/show/devel:languages:perl <code>devel:languages:perl</code>] an, dazu kommen noch einige Community-Pakete mit einer trivial nicht feststellbaren Anzahl an Paketen. Im Paket [https://build.opensuse.org/package/show/devel:languages:perl:CPAN-A/perl-App-cpanminus <code>perl-App-cpanminus</code>] ist <code>cpanm</code> enthalten.

==== RedHat Linux ====
Der RPM bietet eine nicht trivial feststellbare Anzahl an Perl-Paketen an, die Gesamtsumme beträgt um die 8000 - inkl. verschiedener Plattformen (i386, etc.). Auch hier lässt sich festhalten, dass die out of the shelf installierbaren Pakete auf einen Bruchteil der im CPAN verfügbaren reduziert.

==== MacOS ====

Für MacOS gilt, dass das installierte Perl den <code>cpan</code>-Client und eine Auswahl an Module mitbringt. <code>cpanm</code> lässt sich installieren und sollte auch der Weg der Wahl sein. Es ist außerdem möglich, Pakete über [https://www.macports.org/ MacPorts] zu installieren. MacPorts bietet noch weniger Pakete (aktuell 1 797 für Perl 5.26, 1 799 für Perl 5.28) als Debian.

==== Windows ====

[https://www.activestate.com/products/perl/downloads/ ActiveState] bietet eine Perl-Distribution an, die bereits mit einigen Module, 214 bei [https://platform.activestate.com/ActiveState/ActivePerl-5.28 Perl 5.28], ausgeliefert wird.

== Empfohlene Pakete ==

Im FHEM-Umfeld werden aktuell rund 120 CPAN-Pakete (mit Sub-Paketen) eingesetzt die keine [https://www.perl.com/article/what-is-the-perl-core-/ Core-Module] sind und ggf. für ein FHEM-Modul [[Meta|nachinstalliert]] werden müssen:

* Authen::OATH
* AutoLoader
* B
* Carp
* Color
* Compress::Zlib
* Convert::Base32
* Cpanel::JSON::XS
* Crypt::Argon2
* Crypt::CBC
* Crypt::Cipher::AES
* Crypt::ECB
* Crypt::Mode::CBC
* Crypt::MySQL
* Crypt::NaCl::Sodium
* Crypt::Rijndael
* Crypt::Rijndael_PP
* Crypt::URandom
* DBI
* DBI::Const::GetInfoType
* Data::Dumper
* Data::UUID
* Date::Parse
* DateTime
* Device::Firmata
* Device::Firmata::Base
* Device::Firmata::Constants
* Device::Firmata::Error
* Device::Firmata::Language
* Device::Firmata::Platform
* Device::Firmata::Protocol
* Device::SerialPort
* Device::USB
* Digest::CRC
* Digest::SHA1
* Encode::Detect::Detector
* Expect
* File::HomeDir
* HTML::Entities
* HTML::Parser
* HTTP::Cookies
* HTTP::Daemon
* HTTP::Headers
* HTTP::Request
* HTTP::Request::Common
* IO::Interface::Simple
* IO::Socket::Multicast
* IO::Socket::Multicast6
* IO::Socket::SSL
* IO::Socket::Timeout
* IO::String
* Image::ExifTool
* Image::LibRSVG
* Image::Size
* Inline
* JSON
* JSON::MaybeXS
* JSON::XS
* JSON::backportPP
* JsonMod::JSON::Path::Node
* LWP
* LWP::Simple
* LWP::UserAgent~6
* Linux::Inotify2
* LiquidCrystal
* Lirc::Client
* List::MoreUtils
* MIME::Lite
* MP3::Info
* MP3::Tag
* MP3::Tag::CDDB_File
* MP3::Tag::Cue
* MP3::Tag::File
* MP3::Tag::ID3v1
* MP3::Tag::ID3v2
* MP3::Tag::ImageExifTool
* MP3::Tag::ImageSize
* MP3::Tag::Inf
* MP3::Tag::LastResort
* MP3::Tag::ParseData
* Mail::IMAPClient
* Mojolicious~5.54
* Net::Address::IP::Local
* Net::Bonjour
* Net::FTPSSL
* Net::Jabber
* Net::MQTT::Constants
* Net::MQTT::Message
* Net::MQTT::Message::JustMessageId
* Net::Rendezvous
* Net::SIP
* Net::SIP::Packet
* Net::SMTP::SSL
* Net::Telnet
* Net::UPnP::AV::MediaRenderer
* Net::UPnP::AV::MediaServer
* Net::UPnP::ControlPoint
* Net::UPnP::Device
* Net::UPnP::Service
* Net::XMPP::Namespaces
* Nmap::Parser
* Path::Tiny
* Paws::Polly
* Perl::PrereqScanner::NotQuiteLite
* RPC::XML::Client
* RPC::XML::Server
* RiveScript
* SOAP::Lite
* Text::Iconv
* Try::Tiny
* UPnP::Common
* UPnP::ControlPoint
* URI::Escape
* WWW::Jawbone::Up
* Win32::SerialPort
* XML::LibXML
* XML::Parser::Lite

[https://raw.githubusercontent.com/fhem/doc-wiki/master/DE/Howtos/fhem-cpan-modules.txt Liste als plain text], z.B. um sie bei einer automatisierten Installation verwenden zu können. Die Liste wurde mit <code>Perl::PrereqScanner</code> aus dem <code>FHEM/</code>-Verzeichnis erstellt, durch <code>Core::List</code> gefiltert und mit <code>cpanm</code> auf Nicht-CPAN-Module (z.B. <code>FHEM::Meta</code> oder <code>DevIO</code>) geprüft.

[[Kategorie:HOWTOS]]
[[Kategorie:Systemadministration]]
[[Kategorie:Perl]]

CPAN

2020-11-16T09:13:43Z

ChristophMorrison: Wording

= CPAN =

Das CPAN, Comprehensive Perl Archive Network, ist ein weltweit verteiltes Netzwerk für Perl-Module, das seit 1995 besteht und aktuell etwa 200 000 Module umfasst.

Siehe auch hier eine [https://www.cpan.org/modules/INSTALL.html Zusammenfassung des CPAN-Projektes].

== Clients ==

=== Plattformunabhängig ===

Das CPAN bietet drei plattformunabhängige Clients an, von denen zwei hier beschrieben werden. Die ''Empfehlung'' ist, <code>cpanm</code> zu nutzen.

==== cpanminus ====

[https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm cpanminus] (<code>cpanm</code>) ist der bevorzugte Weg, wie CPAN-Pakete installiert werden sollten. cpan-minus ist, wie <code>cpan</code> ein CPAN-Paket, das aber auch für viele Betriebssystem als fertiges Paket portiert wurde.

cpan-minus bietet einen [http://cpanmin.us/ Quickstart] an, der auf jedem System läuft, auf dem Perl installiert ist. Dazu muss folgender Befehl auf der Kommandozeile ausgeführt werden:

<pre>curl -L https://cpanmin.us | perl - App::cpanminus</pre>
Aus Sicherheitsgründen sollte vor Ausführung des Befehls überprüft werden, was unter [http://cpanmin.us/ cpanmin.us] zu finden ist, da ggf. Schadcode unbemerkt eingeschmuggelt werden könnte.

Ist der Client <code>cpanm</code> installiert, kann mit

<pre>cpanm Paket::Name</pre>
ein Paket (in diesem Falle das nicht-existende Paket <code>Paket::Name</code>) installiert werden. Die Option <code>--sudo</code> sorgt dafür, dass cpanminus die Installation als Superuser versucht (ggf. muss ein Passwort eingegeben werden).

==== Exkurs: cpan-outdated ====

Das Paket [https://metacpan.org/pod/distribution/cpan-outdated/script/cpan-outdated <code>cpan-outdated</code>] erzeugt eine cpanminus-kompatible Liste an CPAN-Paketen, die aktualisiert werden können, z.B.

<pre>$ cpan-outdated
A/AN/ANDK/CPAN-2.27.tar.gz
L/LE/LEONT/Test-Harness-3.42.tar.gz
B/BI/BINGOS/Archive-Tar-2.36.tar.gz
T/TO/TODDR/autodie-2.32.tar.gz
R/RU/RURBAN/B-Debug-1.26.tar.gz
I/IL/ILMARI/bareword-filehandles-0.007.tar.gz
P/PJ/PJACKLAM/bignum-0.51.tar.gz
X/XS/XSAWYERX/Carp-1.50.tar.gz
L/LE/LEEJO/CGI-4.47.tar.gz
A/AT/ATOOMIC/Clone-0.45.tar.gz
M/ML/MLEHMANN/common-sense-3.75.tar.gz
P/PM/PMQS/Compress-Raw-Bzip2-2.093.tar.gz
P/PM/PMQS/Compress-Raw-Zlib-2.093.tar.gz
P/PM/PMQS/IO-Compress-2.093.tar.gz
H/HM/HMBRAND/Config-Perl-V-0.31.tgz
A/AT/ATOOMIC/TimeDate-2.33.tar.gz
P/PM/PMQS/DB_File-1.853.tar.gz
H/HU/HURRICUP/Devel-Camelcadedb-v2019.1.tar.gz
P/PJ/PJCJ/Devel-Cover-1.36.tar.gz
A/AT/ATOOMIC/Devel-PPPort-3.58.tar.gz
M/MS/MSHELOR/Digest-SHA-6.02.tar.gz
R/RJ/RJBS/Email-Sender-1.300034.tar.gz</pre>
Sehr nützlich ist die Kombination aus cpanminus und cpan-outdated:

<pre>cpan-outdated | cpanm --sudo</pre>
Diese Befehlssequenz aktualisiert alle aktualisierbaren CPAN-Pakete mit Hilfe von cpanminus (als Superuser).

==== cpan ====

[https://metacpan.org/pod/CPAN <code>cpan</code>] ist der mit jeder Perl-Installation mitgelieferte Client für das CPAN und lässt sich entweder mit

<pre>perl -MCPAN -e shell</pre>
oder

<pre>cpan</pre>
starten. Es wird ein interaktiver Client gestartet; mit <code>h</code> kann eine sehr umfangreiche Hilfe aufgerufen werden.

Ein Modul lässt sich am einfachsten mit

<pre>cpan install PAKET::NAME</pre>
installieren (hier das nicht-existente Paket <code>PAKET::NAME</code>). <code>cpan</code> eignet sich weniger gut um Module zu installieren oder zu aktualisieren, aber sehr gut um nach Paketen zu suchen:

<pre>i /JSON/</pre>
findet jedes Paket, das die Zeichenkette <code>JSON</code> im Bereich Autor, Bundle, Distribution oder Modul enthält. Das sind meist viele Ergebnisse, aber liefert einen Überblick "was geht".

Erfahrungsgemäß ist <code>cpan</code> recht störrisch in der Handhabung. Deshalb empfehle ich die Nutzung von cpanminus.

=== OS-Paketmanager ===

==== Debian und Derivate (Ubuntu, Raspbian, etc.) ====

Vom Debian-Projekt werden viele, aber lange nicht alle, Pakete des CPAN auch als Pakete für den eingebauten Paketmanager <code>apt</code> [https://packages.debian.org/stable/perl/ bereitsgestellt]. Dort sind momentan etwa 4 000 Pakete verfügbar, d.h. rund 2% der im CPAN verfügbaren Pakete. Es ist nicht immer trivial, ein Paket zu finden. Ein einfacher Fall ist z.B. das Paket <code>Readonly</code>, das über <code>cpanm Readonly</code> oder <code>apt-get install libreadonly-perl</code> installiert werden könnte. Im Allgemeinen kann man sagen, dass sich der Name des <code>apt</code>-Paketes aus dem Prefix <code>lib</code>, gefolgt vom Paketnamen in Kleinbuchstaben, bei dem die <code>::</code> durch <code>-</code> ersetzt wurden, und dem Suffix <code>-perl</code> zusammensetzt:

{|
! CPAN
! Debian-Paket
|-
| Rose::URI
| librose-uri-perl
|-
| Sah::Schemas::Rinci
| libsah-schemas-rinci-perl
|}

Kein Beispiel wäre vollständig ohne Ausnahme, z.B.:

[https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>libromana-perligata-perl</code>] installiert das Perl-Paket [https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>Lingua::Romana::Perligata</code>], müsste nach der selbstgewählten Konvention aber <code>liblingua-romana-perligata-perl</code> heißen.

Vorteilhaft ist, dass man die Pakete zusammen mit anderen Debian-Paketen automatisch auf dem aktuellen Stand halten kann, z.B. [https://wiki.debian.org/UnattendedUpgrades <code>unattended-upgrades</code>] - man spart so eine doppelte Implementierung der Updates.

Wiederum von Nachteil ist, dass man mit einer auf ein Release festgelegten Quelle irgendwann auch keine Updates der Perl-Pakete mehr erhält.

==== SuSE Linux ====

YaST bietet aktuell etwa 3 121 der rund 200 000 Pakete in [https://build.opensuse.org/project/show/devel:languages:perl <code>devel:languages:perl</code>] an, dazu kommen noch einige Community-Pakete mit einer trivial nicht feststellbaren Anzahl an Paketen. Im Paket [https://build.opensuse.org/package/show/devel:languages:perl:CPAN-A/perl-App-cpanminus <code>perl-App-cpanminus</code>] ist <code>cpanm</code> enthalten.

==== RedHat Linux ====

==== MacOS ====

Für MacOS gilt, dass das installierte Perl den <code>cpan</code>-Client und eine Auswahl an Module mitbringt. <code>cpanm</code> lässt sich installieren und sollte auch der Weg der Wahl sein. Es ist außerdem möglich, Pakete über [https://www.macports.org/ MacPorts] zu installieren. MacPorts bietet noch weniger Pakete (aktuell 1 797 für Perl 5.26, 1 799 für Perl 5.28) als Debian.

==== Windows ====

[https://www.activestate.com/products/perl/downloads/ ActiveState] bietet eine Perl-Distribution an, die bereits mit einigen Module, 214 bei [https://platform.activestate.com/ActiveState/ActivePerl-5.28 Perl 5.28], ausgeliefert wird.

== Empfohlene Pakete ==

Im FHEM-Umfeld werden aktuell rund 120 CPAN-Pakete (mit Sub-Paketen) eingesetzt die keine [https://www.perl.com/article/what-is-the-perl-core-/ Core-Module] sind und ggf. für ein FHEM-Modul [[Meta|nachinstalliert]] werden müssen:

* Authen::OATH
* AutoLoader
* B
* Carp
* Color
* Compress::Zlib
* Convert::Base32
* Cpanel::JSON::XS
* Crypt::Argon2
* Crypt::CBC
* Crypt::Cipher::AES
* Crypt::ECB
* Crypt::Mode::CBC
* Crypt::MySQL
* Crypt::NaCl::Sodium
* Crypt::Rijndael
* Crypt::Rijndael_PP
* Crypt::URandom
* DBI
* DBI::Const::GetInfoType
* Data::Dumper
* Data::UUID
* Date::Parse
* DateTime
* Device::Firmata
* Device::Firmata::Base
* Device::Firmata::Constants
* Device::Firmata::Error
* Device::Firmata::Language
* Device::Firmata::Platform
* Device::Firmata::Protocol
* Device::SerialPort
* Device::USB
* Digest::CRC
* Digest::SHA1
* Encode::Detect::Detector
* Expect
* File::HomeDir
* HTML::Entities
* HTML::Parser
* HTTP::Cookies
* HTTP::Daemon
* HTTP::Headers
* HTTP::Request
* HTTP::Request::Common
* IO::Interface::Simple
* IO::Socket::Multicast
* IO::Socket::Multicast6
* IO::Socket::SSL
* IO::Socket::Timeout
* IO::String
* Image::ExifTool
* Image::LibRSVG
* Image::Size
* Inline
* JSON
* JSON::MaybeXS
* JSON::XS
* JSON::backportPP
* JsonMod::JSON::Path::Node
* LWP
* LWP::Simple
* LWP::UserAgent~6
* Linux::Inotify2
* LiquidCrystal
* Lirc::Client
* List::MoreUtils
* MIME::Lite
* MP3::Info
* MP3::Tag
* MP3::Tag::CDDB_File
* MP3::Tag::Cue
* MP3::Tag::File
* MP3::Tag::ID3v1
* MP3::Tag::ID3v2
* MP3::Tag::ImageExifTool
* MP3::Tag::ImageSize
* MP3::Tag::Inf
* MP3::Tag::LastResort
* MP3::Tag::ParseData
* Mail::IMAPClient
* Mojolicious~5.54
* Net::Address::IP::Local
* Net::Bonjour
* Net::FTPSSL
* Net::Jabber
* Net::MQTT::Constants
* Net::MQTT::Message
* Net::MQTT::Message::JustMessageId
* Net::Rendezvous
* Net::SIP
* Net::SIP::Packet
* Net::SMTP::SSL
* Net::Telnet
* Net::UPnP::AV::MediaRenderer
* Net::UPnP::AV::MediaServer
* Net::UPnP::ControlPoint
* Net::UPnP::Device
* Net::UPnP::Service
* Net::XMPP::Namespaces
* Nmap::Parser
* Path::Tiny
* Paws::Polly
* Perl::PrereqScanner::NotQuiteLite
* RPC::XML::Client
* RPC::XML::Server
* RiveScript
* SOAP::Lite
* Text::Iconv
* Try::Tiny
* UPnP::Common
* UPnP::ControlPoint
* URI::Escape
* WWW::Jawbone::Up
* Win32::SerialPort
* XML::LibXML
* XML::Parser::Lite

[https://raw.githubusercontent.com/fhem/doc-wiki/master/DE/Howtos/fhem-cpan-modules.txt Liste als plain text], z.B. um sie bei einer automatisierten Installation verwenden zu können. Die Liste wurde mit <code>Perl::PrereqScanner</code> aus dem <code>FHEM/</code>-Verzeichnis erstellt, durch <code>Core::List</code> gefiltert und mit <code>cpanm</code> auf Nicht-CPAN-Module (z.B. <code>FHEM::Meta</code> oder <code>DevIO</code>) geprüft.

[[Kategorie:HOWTOS]]
[[Kategorie:Systemadministration]]
[[Kategorie:Perl]]

HM-CFG-USB USB Konfigurations-Adapter

2020-09-03T14:47:55Z

ChristophMorrison:

{{Infobox Hardware
|Bild=HM-CFG-USB-2.jpg
|Bildbeschreibung=HomeMatic USB Konfigurationsadapter (Version 2)
|HWProtocol=HomeMatic
|HWType=Interface/Gateway
|HWCategory=HomeMatic
|HWComm=868,3 MHz
|HWChannels=
|HWVoltage=5 V
|HWPowerConsumption=
|HWPoweredBy=USB-Bus
|HWSize=V1: 40 x 90 x 25 mm V2: 28 x 84 x 11,5 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]

|HWManufacturer=eQ-3
}}
Der [[HomeMatic]] '''USB Konfigurations-Adapter''' ist ein USB-Stick, der außer zur Konfiguration von HomeMatic-Komponenten auch als [[Interface]] zwischen FHEM und HomeMatic-Geräten benutzt werden kann. Er existiert in zwei Versionen: der älteren HM-CFG-USB und der neueren HM-CFG-USB2. Die folgenden Beschreibungen gelten für beide Versionen, es sei denn, es ist ausdrücklich eine spezifische Version genannt.

== Einbindung in FHEM ==
Im FHEM-Forum wird die Einbindung als Interface in diesem {{Link2Forum|Topic=13071}} beschrieben und diskutiert. Im {{Link2Forum|Topic=13071|Message=79872|LinkText=Eröffnungsbeitrag}} wird eine gut funktionierende HMLAN-Emulationssoftware [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland] von ihrem Entwickler vorgestellt, um den HM-CFG-USB in FHEM zu integrieren. Die HMLAN-Emulationssoftware muss zunächst kompiliert und installiert werden. Anschließend wird der HM-CFG-USB (üblicherweise auf localhost) genau wie [[HM-CFG-LAN LAN Konfigurations-Adapter|HMLAN]] in FHEM eingebunden.

=== Einrichtung unter Linux ===
Die Schritte zur Kompilierung und Installation hat der hmland-Entwickler sowohl auf der [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland-Internetseite] in Englisch (kurz) als auch im oben genannten {{Link2Forum|Topic=13071|Message=79872|LinkText=Eröffnungsbeitrag}} in Deutsch (ausführlich) dargestellt. Die dort gemachten Angaben werden auch bei Bedarf aktualisiert und sind deshalb der beste Anlaufpunkt für Kompilierung und Installation.

{{Randnotiz|RNTyp=Info|RNText='''Skript zur Kompletteinrichtung unter Linux'''
Dieser {{Link2Forum|Topic=13071|Message=190887|LinkText=Bericht}} im Forum stellt ein Script vor, das ''hmland'' herunterlädt, übersetzt (kompiliert), installiert sowie ein init-Script anlegt, so dass fast keine manuellen Eingriffe mehr notwendig sind.}}
Die nachfolgenden Angaben in diesem Abschnitt sind rein zu Informationszwecken (noch) enthalten:

Zunächst muss die HMLAN-Emulationssoftware kompiliert werden. Analog zu [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb dieser Beschreibung] ist die Vorgehensweise die folgende (in Debian/Ubuntu/Raspbian):
<syntaxhighlight lang="bash">
cd /opt/
apt-get install build-essential libusb-1.0-0-dev make gcc git
git clone git://git.zerfleddert.de/hmcfgusb
cd hmcfgusb
make
</syntaxhighlight>

Danach kann der Dienst (zu Testzwecken sind Debugging-Ausgaben mit <code>-D</code> aktiviert) gestartet werden:
:<code> /opt/hmcfgusb/hmland -p 1234 -D</code>

==== Start als Daemon ====
Um ''hmland'' automatisch als Daemon bei '''init.d Systemen''' zu starten, kann ein init-Script genutzt werden. Die Quellen von ''hmland'' enthalten ein solches Script im <code>debian/</code> Unterverzeichnis:

<syntaxhighlight lang="bash">
cp /opt/hmcfgusb/debian/hmland.init /etc/init.d/hmland
cp /opt/hmcfgusb/debian/hmland.default /etc/default/hmland
</syntaxhighlight>

Einstellungen, beispielsweise der Port, auf dem ''hmland'' hört, können (und sollten) in der Datei <code>/etc/default/hmland</code> vorgenommen werden. Wichtig: Wenn diese Anleitung befolgt wurde, muss in der Datei <code>/etc/init.d/hmland</code> die folgende Zeile wie folgt angepasst werden (<code>/hm</code> aus dem Pfad entfernen), damit der automatische Start des Daemon klappt:
<syntaxhighlight lang="bash">
DAEMON=/opt/hmcfgusb/$NAME # Introduce the server's location here
</syntaxhighlight>

Die kopierte Datei mit <code>chmod 755 /etc/init.d/hmland</code> ausführbar machen, anschließend kann ''hmland'' mit folgendem Befehl gestartet werden:
:<code>/etc/init.d/hmland start</code>

==== Start mit systemd ====
Bei Distributionen, die '''systemd''' einsetzen (z.B. Debian Stretch) kann folgende Konfigurationsdatei verwendet werden:
<syntaxhighlight lang="bash">
[Unit]
Description=Homematic LAN Adapter service
After=network.target

[Service]
ExecStart=/opt/hmcfgusb/hmland -p 1234

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Dabei muss dann natürlich der Port (1234) an die eigene Konfiguration angepasst werden und auch der Pfad wo sich der <Code> hmland</code> befindet, wenn man sich an oben stehendem Beispiel orientiert wäre das dann <Code>/opt/hmcfgusb/</code>
Diese Datei muss dann als <Code>hmland.service</code> unter <syntaxhighlight lang="bash">/etc/systemd/system</syntaxhighlight> abgelegt werden.
Nun muss einmalig der Befehl
<syntaxhighlight lang="bash">systemctl daemon-reload</syntaxhighlight> ausgeführt werden damit die neuen Dateien eingelesen werden.
Mit dem Befehl <syntaxhighlight lang="bash">systemctl enable hmland</syntaxhighlight> wird dafür gesorgt, dass bei einem Systemstart hmland automatisch gestartet wird
Mit <syntaxhighlight lang="bash">systemctl status hmland </syntaxhighlight> kann dann noch geprüft werden ob der Service läuft

==== Start mit upstart ====
Bei Distributionen, die '''Upstart''' einsetzen (z.B. xbian) kann folgende Konfigurationsdatei verwendet werden:
<syntaxhighlight lang="bash">
# HMLAND

description "hmland"

start on starting fhem
stop on stopped fhem

respawn
expect fork

chdir /opt/hmcfgusb
exec /opt/hmcfgusb/hmland -d -l 127.0.0.1 -p 1234
</syntaxhighlight>

Die Datei sollte als <code>/etc/init/hmland.conf</code> angelegt werden. Mit dem Befehl
:<code>initctl reload-configuration </code>
wird Upstart angewiesen, seine Konfiguration erneut einzulesen. Danach kann der Dienst ''hmland'' mit
:<code>service hmland start </code>
gestartet werden. <code>hmland</code> wird jetzt immer vor FHEM gestartet und nach FHEM beendet.

==== Start über FHEM Startskript ====
Ausprobiert auf einem BBB mit Debian, eigentlich ist das alles von Betateilchen:

Zunächst hmland kompilieren wie oben beschrieben, bis zum make. Das muss erfolgreich durchgelaufen sein.

Dann geht es weiter:
:<code>sudo cp hmcfgusb.rules /etc/udev/rules.d/ </code>

Jetzt das FHEM Startskript anpassen (in den Blöcken 'start' und 'stop' muss quasi nur jeweils 1 Zeile eingefügt werden:

Damit editiert man das FHEM Startskript:
:<code>sudo nano /etc/init.d/fhem </code>

Und so sollten die Blöcke anschließend aussehen (bitte nur jeweils die Zeile mit hmland einfügen)
<syntaxhighlight lang="bash">
'start')
echo "Starting fhem..."
/opt/hmcfgusb/hmland -d -p 1234
perl fhem.pl fhem.cfg
RETVAL=$?
;;

'stop')
echo "Stopping fhem..."
perl fhem.pl $port "shutdown"
RETVAL=$?
pkill hmland
</syntaxhighlight>

So wird hmland vor FHEM gestartet und nach FHEM beendet. Letztlich erspart es Probleme mit den diversen Startskripten und ihren Rechten.

Es dauert nach dem Start von FHEM noch einige Sekunden, bis hmland fertig geladen ist. In dieser Zeit kann es zu fehlerhaften Einträgen im Logfile kommen.

=== Einrichtung auf Synology DiskStations ===
Packages für DSM5.2 finden sich hier:
https://github.com/mkunzmann/spksrc/releases/tag/0.101-3

Welches Package für welche DS kann man hier sehen:
https://github.com/SynoCommunity/spksrc/wiki/Architecture-per-Synology-model

Einfach das passende Package installieren und dann kann man den hmland über den Synology Package-Manager starten und stoppen. Während der Installation kann man den Port für hmland festlegen. Bitte einen Port > 1024 wählen, da der hmland nicht als root läuft. Außerdem kann ein Logfile angegeben werden. Hier am besten eine Datei auf einem USB Stick angeben die für jedermann schreibbar sein muss. Damit sollten die Platten nach wie vor in den Standby gehen.

=== Einrichtung unter Mac OS X ===
Wie unter Linux braucht man die HMLAN-Emulationssoftware hmland, die man aus Quelltexten erstellen muss. Dazu muss man die Bibliothek libusb installieren, entweder mit einem der Paketmanager wie Fink, MacPorts oder Homebrew oder direkt aus den Quellentexten (Beispiel: "fink install libusb1-shlibs libusb1"). Hat man wie bei Linux das Quelltextarchiv für hmland heruntergeladen und ausgepackt, müssen die Dateien Makefile und hmcfgusb.c angepasst werden.

Im Makefile muss man den Pfad zur libusb anpassen. Hat man libusb mit fink installiert, muss man, "/opt/local/" durch "/sw/" bei den CFLAGS und den LDFLAGS ersetzen und
das "-lrt" aus den LDLIBS entfernen. Die Library librt gibt es bei Mac OS X nicht und wird anscheinend auch nicht gebraucht. (Stimmt das eigentlich?)

In der Datei hmcfgusb.c muss man die Zeilen 130-134 mit dem Aufruf libusb_detach_kernel_driver auskommentieren oder löschen. Der geht nicht auf Mac OS X.

Nach den Änderungen in den zwei Dateien, kann man wie bei Linux den Dämon hmland mit dem Kommando "make" erzeugen und mit "./hmland" ausführen. Automatisches Starten beim Booten mit launchd ist noch nicht probiert.

Beim Start von hmland sollte man folgende Fehlermeldung in einer Endlos-Schleife erhalten:
<syntaxhighlight lang="text">
Datum Zeit: Client 127.0.0.1 connected!
Can't claim interface: Access denied (insufficient permissions)
Can't find/open hmcfgusb!
Datum Zeit: Connection to 127.0.0.1 closed!
</syntaxhighlight>

Auch ein Start von hmland mit Superuser-Rechten ändert daran nichts. Damit das claim interface klappt, muss man eine codeless kext in den Ordner /Library/Extensions legen. Ich habe dieses (http://mspdebug.sourceforge.net/misc/ex430rf2500-kext.zip) herunter geladen. Damit es funktioniert, muss man aber in der Datei Info.plist des Bundle die Properties idProduct und idVendor ändern, entweder mit dem Property List Editor oder einem anderen Texteditor. Die beiden Properties sind etwas versteckt bei Information Property List → IOKitPersonalities → ComIntf. Bei DebugIntf und DeviceDriver scheint man es nicht ändern zu müssen, aber schaden kann es nicht.

<syntaxhighlight lang="text">
idProduct: 49167
idVendor: 6943
</syntaxhighlight>

Die Rechte des kext-Bundles müssen auch noch gesetzt werden:
<syntaxhighlight lang="bash">
chmod -R 755 ex430rf2500.kext
chown -R root:wheel ex430rf2500.kext
</syntaxhighlight>

Danach die Datei ex430rf2500.kext in den Ordner /Library/Extensions legen und hmland sollte dann funktionieren.

Es kann sein, dass ab Mac OS X 10.9 der Trick mit dem codeless kext nicht mehr funktioniert, aber noch ist das nicht getestet oder bestätigt. Langfristig kann man vielleicht auch eine kext mit einem Treiber für den HM-CFG-USB USB erstellen

=== Einrichtung unter Windows ===
Bei der Einrichtung und vermutlich auch dem Betrieb unter Windows 8.1 sind wegen der erweiterten Energieverwaltungsfunktionen die von eQ-3 [http://www.eq-3.de/Downloads/eq3/pdf_FAQ/Funk-Konfigurationsdapter-USB_Windos_8.1.pdf zusammengestellten Tipps] zu befolgen.

=== Definition(en) in der FHEM-Konfiguration ===
In der FHEM [[Konfiguration]] muss noch, sofern/sobald der ''hmland'' läuft, das Device eingerichtet werden mit den folgenden Anweisungen:
:<code>define '''hmusb''' HMLAN 127.0.0.1:1234 </code>
wobei '''hmusb''' der frei wählbare Devicename ist. Anschließend sollte bzw. muss noch mit
:<code>attr '''hmusb''' hmId <'''hmId'''> </code>
eine '''hmId''' zugeordnet werden (dabei bitte auch die Hinweise und Regeln beachten, die im Zusammenhang mit der [[Virtueller Controller VCCU|VCCU]] beschrieben sind!

== Firmware Update ==
Der Firmware Update (unter Linux) ist ebenfalls auf der [https://git.zerfleddert.de/cgi-bin/gitweb.cgi/hmcfgusb hmland-Internetseite] beschrieben. Auch die letzte bekannte Firmware-Version (0.967) steht dort zur Verfügung.

== Bekannte Probleme ==
=== Verbindung zu neueren hmland-Versionen nicht stabil ===
Seit Version 0.100 meldet sich die HMLAN-Emulationssoftware als USB-Interface bei FHEM. Ältere FHEM-Versionen (vor dem 19.6.2015) brechen deshalb die Verbindung ab, da sie nur ein LAN-Interface erwarten.

Lösung: Kommandozeilenparameter <code>-I</code> dem hmland-Aufruf hinzufügen, dann meldet sich dieser wieder als LAN-Interface.

=== Stick nicht (mehr) ansprechbar ===
Zitat aus dem {{Link2Forum|Topic=32502|Message=249122|LinkText=FHEM-Forum}}:
:''... befürchte ich, dass dein Stick das Zeitliche gesegnet hat. Machen die Dinger leider sehr gerne... Ganz besonders beim Modus-Wechsel vom 10k- in den 100k-Modus, wenn man bei irgendeinem Device ein Firmwareupdate durchführt. Die gute Nachricht ist, dass der Fehler bei sämtlichen Händlern bekannt ist und anstandslos getauscht wird.''

=== Raspberry Pi ===
Der USB-Stack am Raspberry Pi ist für viele Probleme verantwortlich. Daher sieht man öfter Fehlermeldungen:
:<code>usb-transfer took more than 100ms (1039ms), this may lead to timing problems!</code>

Da das Timing bei HomeMatic wichtig ist führt das zu vielen Retransmits und zu unzuverlässigen Aktoren. Als Workaround kann man den USB-Stack auf die deutlich langsamere Version 1.1 stellen. Dazu fügt man folgenden Text am Anfang der Datei /boot/cmdline.txt ein:
:<code>dwc_otg.speed=1</code>

== Weitergehende Informationen ==
Es sind zwei Versionen des HM-CFG-USB im Umlauf:
{{Randnotiz|RNTyp=r|RNText=Stand März 2016 ist allem Anschein nach kein HM-CFG-USB mehr im ELV Programm enthalten!}}
* HM-CFG-USB-2: die aktuelle Version; Kennzeichen dieser Version:
** Größe: 28 x 84 x 11,5 mm
** Gewicht: 18 g
** Antenne innenliegend
* HM-CFG-USB: Vorgängerversion; Stand 12/2013 noch Restbestände im Handel verfügbar. Dokumentation ([http://files.voelkner.de/625000-649999/646462-an-01-ml-HM_Konfigurationsadapter_CFG_USB_de_en.pdf Völkner]); Kennzeichen:
** Anschluss per separatem USB-Kabel
** abstehende Stabantenne
** Größe: 40 x 90 x 25 mm
** Gewicht: 45 g

== Links ==
* Bedienungsanleitung [http://www.eq-3.de/Downloads/eq3/pdf_produkte/HM-CFG-USB-2_-UM-eQ-3-150129-web.pdf HM-CFG-USB-2, PDF]
* FHEM-Forums {{Link2Forum|Topic=13071}}: HomeMatic USB Konfigurations-Adapter (HM-CFG-USB) in FHEM nutzen
* [http://www.eq-3.de/produkt-detail-zentralen-und-gateways/items/homematic-funk-konfigurationsadapter-usb.html eQ-3 Produktseite] zum "HomeMatic Funk-Konfigurationsadapter USB"; Downloads, technische Daten, etc.

[[Kategorie:HomeMatic Components]]
[[Kategorie:Interfaces]]
[[Kategorie:OSX]]
[[Kategorie:868MHz]]

MQTT

2020-08-17T21:43:51Z

ChristophMorrison: Fixed perl packages

MQTT ist ein Protokoll ("Message Queue Telemetry Transport"), mit dem Daten und Befehle zwischen verschiedenen Geräten ausgetauscht werden. Die Kommunikation erfolgt dabei über einen zentralen MQTT-Server, in alter Nomenklatur auch ''Broker'' genannt.

MQTT wurde entwickelt, um möglichst effizient, sicher und mit wenig Datenlast zu kommunizieren. MQTT ist nachrichtenorientiert, daher muss ein Client nicht beständig beim Server anfragen, ob neue Daten vorliegen. Heute findet sich MQTT vor allem im Bereich des ''Internet of Things'' (IoT). MQTT kann leicht mit FHEM verbunden werden, ohne dass dabei größerer CPU- oder Datenverbrauch entsteht.

== Eine sehr kurze Einführung in MQTT ==
Die folgende Einführung kann eine vollwertige Einleitung wie beispielsweise [https://github.com/mqtt/mqtt.github.io/wiki diese Wikieinträge] nicht ersetzen.

Bei MQTT findet die nachrichtenbasierte Kommunikation zwischen einzelnen Teilnehmern<ref>Teilnehmer in diesem Sinne kann ein Stück Hardware mit einer MQTT-fähigen firmware sein, ein auf einem Computer laufendes Script (einschließlich eines MQTT-Server-Dienstes wie ''mosquitto'' oder ''MQTT2_SERVER'', kurz: alles mögliche sein. Dadurch kann auch ein einzelner Computer unter mehreren ClientID's am MQTT-Datenaustausch beteiligt sein.</ref> in der Regel nicht direkt statt. Stattdessen werden alle Nachrichten von einem Teilnehmer an einen Serverdienst, den MQTT-Server (früher ''Broker'' genannt) übergeben, der dann dafür sorgt, dass die Nachricht an alle (berechtigten) anderen Teilnehmer verteilt wird, die sich für derartige Nachrichten "interessieren". Wenn also ein Teilnehmer ohne Server-Funktion (Client) Daten von einem bestimmten anderen Teilnehmer (anderer Client) empfangen will, muss es vorher dem MQTT-Server (Broker) mitteilen, dass er die Nachrichten dieses anderen Teilnehmers abonniert (deshalb wird dieser Vorgang als ''subscribe'' bezeichnet). Im IoT ist besonders interessant, dass Sender und Empfänger von Nachrichten durch den MQTT-Server vollständig entkoppelt werden können - jemand, der Daten bereit stellt, muss sich also nicht darum kümmern, wer diese Daten empfängt<ref>Aufgrund dieser Funktionsweise sollte allerdings darauf geachtet werden, die Möglichkeiten des jeweiligen Servers zur Sicherung der Daten gegen unberechtigten Zugriff zu nutzen, insbesondere wenn die Art der Daten oder die sich hierdurch ergebenden Möglichkeiten, z.B. Schaltvorgänge in der realen Welt auszulösen, dies notwendig macht!</ref>.

Eine Nachricht besteht im Wesentlichen aus den folgenden Elementen:
*ClientID - das ist die Kennung des Senders einer Nachricht<ref>Diese kann sich bei der Weitergabe der Nachricht ändern: Zunächst sendet ein Client eine Nachricht unter seiner ClientID, der MQTT-Server wird diese dann in der Regel durch seine Kennung ersetzten, wenn er die Nachricht an einen Abonnenten - der auch ein weiterer MQTT-Server sein kann - weitergibt.</ref>
*Topic - das ist die Adresse, an die eine Nachricht gesendet wird, bzw. von wo sie abgeholt werden kann (so ähnlich wie ein Postfach in der realen Welt). Topics sind einfache Strings, die mit Schrägstrichen getrennt werden (keine Leerzeichen und nur sehr wenige Sonderzeichen erlaubt). Ein Topic könnte beispielhaft so lauten: <code>zuHause/1OG/Kueche/Licht/state</code>. Diese Topics beinhalten also eine Hierarchie der Objekte - hier im Beispiel sind sie zuerst danach sortiert, ob sie sich zu Haus befinden, dann wird nach Stockwerken sortiert und im ersten Stock schaut man auf die Küche sowie das dort vorhandene Licht.
*Payload - das ist der Inhalt der Nachricht, oft handelt es sich um Befehle oder Daten.
*Quality of Service - soll geprüft werden, ob die Nachricht zugestellt wurde und wenn ja, mit welcher "Tiefe"?
*Retained Message.
Details bitte in der oben genannten Einführung nachlesen.

MQTT kommuniziert üblicherweise über Port 1883, es können aber unter derselben Netzwerkadresse an unterschiedlichen Ports auch mehrere Serverdienste bereitstehen.

== Installation in FHEM ==
Um MQTT in FHEM zu nutzen, benötigt man (mindestens) einen MQTT-Server. Es gibt zwei Möglichkeiten: Man kann FHEM-externe Server-Software (oder auch einen oder mehrere im Internet bereitstehende MQTT-Server) verwenden oder man kann die MQTT-Serverkomponente aktivieren, die mit {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} in FHEM direkt bereitsteht. Hier werden kurz beide Installationswege erläutert, zwingend ist nur einer, da eben mindestens ein MQTT-Serverdienst aktiv sein muß.

Die nachfolgenden Schaubilder zeigen schematisch die in FHEM zur Verfügung stehenden Wege der Einbindung von Hard- und/oder Softwarekomponenten, die über das MQTT-Protokoll Daten austauschen.
<gallery>
Datei:Mqtt2 server.png|Datenaustausch mit MQTT-Geräten, wenn MQTT2_SERVER als internem MQTT-Serverdienst verwendet wird
Datei:Mqtt2 client v extern server.png|Datenaustausch mit MQTT-Geräten, wenn MQTT2_CLIENT iVm. mosquitto als externem MQTT-Serverdienst verwendet wird
Datei:00 mqtt pm.png|Datenaustausch mit MQTT-Geräten, wenn das Modul ''MQTT'' (00_MQTT.pm) iVm. mosquitto als externem MQTT-Serverdienst verwendet wird
</gallery>
=== FHEM als MQTT-Server ===
Die mit dem Modul {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} bereitstehende Serverkomponente kann z.B. wie folgt aktiviert werden:
defmod myBroker MQTT2_SERVER 1883 global
Dieses [[Gerät]] übernimmt dann die Kommunikation mit den externen Clients (und wird von diesen behandelt, wie jeder andere MQTT-Server auch<ref>Bitte beachten Sie, dass (Stand: Juni 2019) MQTT2_SERVER nicht alle features des MQTT-Protokolls unterstützt.</ref>) und verteilt die eingehenden Nachrichten als IO-Device<ref>im Sinne des [[DevelopmentModuleIntro#Zweistufiges Modell für Module|2-stufigen Modulkonzepts]]</ref> für die Client-Module [[MQTT2_DEVICE]]<ref>Die Zahl 2 in den Modulnamen verweist nur darauf, dass es sich um eine neuere Modulfamilie handelt; die Kommunikation mit den externen Komponenten unterscheidet sich nicht zu den älteren Modulen, die vor dem Jahr 2018 genutzt werden konnten.</ref> und {{Link2CmdRef|Anker=MQTT_GENERIC_BRIDGE|Lang=de|Label=MQTT_GENERIC_BRIDGE}}.
Ein weiterer Vorteil dieser Lösung besteht darin, dass man ein MQTT2_SERVER-Device mit Hilfe von [[allowed]] absichern kann, was auch SSL-verschlüsselte Kommunikation ermöglicht. '''Hinweis:''' In diesem Fall muss User bzw. Passwort auch in den entsprechenden Geräten eingetragen werden.

{{Hinweis|Wenn Sie beabsichtigen, diese Variante zu verwenden, sollten Sie als nächstes die [[MQTT2-Module - Praxisbeispiele|Praxisbeispiele zu den MQTT2-Modulen]] lesen, und ggf. später wieder hierher zurückkehren. Dort findet sich auch ein Abschnitt zu dem auf den Grafiken zu den MQTT2-IO-Modulen enthaltenen [[MQTT2-Module_-_Praxisbeispiele#bridgeRegexp|bridgeRegexp]]-Attribut.}}

=== FHEM-externer Broker ===
==== Beispiel: mosquitto ====
Eine gern verwendete MQTT-Server-Software ist [http://mosquitto.org Mosquitto]. Sie kann ohne weiteres auf dem Raspberry Pi, der bereits eine FHEM-Installation besitzt, installiert werden und wird keine größere CPU- oder Netzwerklast verursachen.

Eine Anleitung zur Installation findet sich beispielsweise in diesem [http://blog.wenzlaff.de/?p=6487 Blogeintrag]. Im wesentlichen beschränkt sich die Installation eines MQTT Servers aber auf wenige Arbeitsschritte. Bei ''stretch'' ist ''Mosquitto'' bereits in der Distribution enthalten und kann - zusammen mit dem client Befehl ''mosquito_sub'', der weiter unten benötigt wird, wie folgt installiert und getestet werden<ref>Die für den Betrieb mit FHEM erforderlichen Perl-Module sind teilweise (noch) nicht in den Paketquellen verfügbar. Sie können dennoch statt mit cpan auch als Debian-Paket mit Hilfe von ''dh-make-perl'' installiert werden, wobei vorab das in den Paketquellen bereits vorhandene ''libmodule-pluggable-perl'' installiert werden sollte: 
<code>sudo apt-get install dh-make-perl 
dh-make-perl --install --cpan Net::MQTT::simple 
dh-make-perl --install --cpan Net::MQTT::Constants 
sudo dpkg -i libnet-mqtt-simple-perl*.deb 
sudo dpkg -i libnet-mqtt-perl*.deb</code></ref>:
{{Randnotiz|RNTyp=g|RNText=Für ältere Distributionen (hier am Beispiel von ''jessie'') muß ggf. aus einer zusätzlichen Paketquelle installiert werden:
wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key
sudo apt-key add mosquitto-repo.gpg.key
cd /etc/apt/sources.list.d/
sudo wget http://repo.mosquitto.org/debian/mosquitto-jessie.list
sudo apt-get update
Danach kann die eigentliche Installation durchgeführt werden wie links für ''stretch'' beschrieben.}}<source lang="bash">
sudo apt-get install mosquitto mosquitto-clients

# MQTT Server Test
sudo service mosquitto status

# Start / Stop des Servers
sudo service mosquitto stop
sudo service mosquitto start
</source>
Danach ist der RPi mit <nowiki>shutdown restart</nowiki> neu zu starten.

==== IO-Module für externe MQTT-Server ====
Damit FHEM mit dem MQTT-Server kommuniziert, muss noch ein IO-Device angelegt werden. Dabei stehen zwei Varianten zur Wahl, das Modul [[MQTT (Modul)|MQTT]] oder seit Ende 2018 [[MQTT2_CLIENT]].

Beide Module können auch dazu genutzt werden, um Daten zwischen zwei FHEM-Installationen auszutauschen, insbesondere kann auch 00_MQTT.pm als Client für einen MQTT2_SERVER eingesetzt werden, der '''auf der anderen Installation''' als MQTT-Serverdienst eingerichtet ist. Darüber hinaus bestehen eine Vielzahl von Kombinationsmöglichkeiten der diversen IO-Module, wenn die Installation auf mehrere Server verteilt ist.
Auf einer FHEM-Installation wird jedoch in der Regel nur eines der IO-Module benötigt.

===== MQTT2_CLIENT =====
Ein MQTT2_CLIENT-IO-Device wird z.B. angelegt mit
define myBroker MQTT2_CLIENT 10.0.0.5:1883 ## bitte EIGENE IP-Adresse eintragen

{{Hinweis|Wenn Sie beabsichtigen, MQTT2_CLIENT zu verwenden, sollten Sie zuerst die [[MQTT2-Module - Praxisbeispiele|Praxisbeispiele zu den MQTT2-Modulen]] lesen, und dabei die Hinweise im Artikel [[MQTT2_CLIENT]] beachten.}}

Ein MQTT2_CLIENT-Device kann ebenfals mit Hilfe von [[allowed]] abgesichert werden, um z.B. SSL-verschlüsselte Kommunikation zu ermöglichem. Client-Module zu diesem IO-Typ sind wiederum [[MQTT2_DEVICE]] und {{Link2CmdRef|Anker=MQTT_GENERIC_BRIDGE|Lang=de|Label=MQTT_GENERIC_BRIDGE}}.

===== MQTT (Modul) =====
Vorab werden für diese Variante weitere Perl-Pakete benötigt:
<source lang="bash">
# Perl Version ausgeben
perl -v
# Perl MQTT Module nachinstallieren (läuft ein paar Minuten)
sudo cpan install Net::MQTT::Simple
sudo cpan install Net::MQTT::Constants
</source>

Ein IO-Device des Typs MQTT wird z.B. angelegt mit
{{Randnotiz|RNTyp=g|RNText=Sofern der Broker mit FHEM über localhost kommuniziert, kann als IP 127.0.0.1 verwendet werden.}}
define myBroker MQTT 10.0.0.5:1883 ## bitte EIGENE IP-Adresse eintragen
{{Randnotiz|RNTyp=g|RNText=Außerhalb der offiziellen Quellen sind auch einige ältere Varianten des Moduls MQTT_DEVICE verfügbar, die jeweils spezielle Anforderungen (z.B. für Zigbee2mqtt) separat abbilden. Diese werden hier nicht gesondert behandelt, da solche Sonderfälle heute generischer und einfacher durch den Einsatz von MQTT2_DEVICE abzubilden sind.}}Client-Device-Module zum Modul [[MQTT (Modul)|MQTT]] sind [[MQTT_DEVICE]], {{Link2CmdRef|Anker=MQTT_BRIDGE|Lang=de|Label=MQTT_BRIDGE}} (veraltet) und {{Link2CmdRef|Anker=MQTT_GENERIC_BRIDGE|Lang=de|Label=MQTT_GENERIC_BRIDGE}}. Da ''MQTT_DEVICE'' payload im JSON-Format (im Unterschied zu MQTT2_DEVICE) nicht selbst verarbeiten kann wird hier zusätzlich das Modul {{Link2CmdRef|Anker=expandJSON|Lang=de|Label=expandJSON}} benötigt, um den {{Link2Forum|Topic=66761|LinkText=JSON String auszuwerten}}.

=== Performancefragen... ===
...oder was sollte man als Lösung wählen, wenn man in die MQTT-Welt einsteigt<ref>vgl. hierzu diesen {{Link2Forum|Topic=94768|Message=875714|LinkText=Beitrag}} von Rudolf König</ref>?
Grundsätzlich sollte man davon ausgehen, dass innerhalb von FHEM die Verarbeitung derselben Daten näherungsweise denselben Aufwand bedeuten, unabhängig davon, welche der Implementierungen (''MQTT2_CLIENT'', ''MQTT'' oder ''MQTT2_SERVER'') man konkret wählt.
Ein externer Broker hat daher vor allem dann Vorteile, wenn die MQTT Daten überwiegend für was anderes (nicht FHEM) verwendet werden, oder MQTT zweckentfremdet wird (wie z.Bsp. für Musikübertragung). Nutzt man das MQTT-Protokoll dagegen vorwiegend innerhalb von FHEM, ist eher der Einsatz von MQTT2_SERVER in Betracht zu ziehen. Dieser soll Anfängern die Anbindung von MQTT Geräten in FHEM einfacher machen. Wer später merkt, dass er doch einen externen Broker benötigt, kann dann immer noch auf MQTT2_CLIENT in Verbindung mit einem anderen Broker wechseln.
Dagegen ist der Weg von MQTT_DEVICE zu MQTT2_DEVICE mit erheblich mehr Aufwand verbunden.

=== Kommunikation zu sonstigen FHEM-Geräten über MQTT ===

Möchte man Daten von einem [[Gerät]] (im FHEM-Sinn), das '''nicht''' vom Typ ''MQTT2_DEVICE'' oder ''MQTT_DEVICE'' (je nach IO-Modul) ist, per MQTT-Protokoll versenden (z.B. für eine andere Visualisierungslösung als FHEMWEB, oder als FHEM2FHEM-Ersatzlösung), oder diese sonstigen Geräte über MQTT-Anweisungen von außen steuern können, hat man mehrere Möglichkeiten:

==== MQTT_GENERIC_BRIDGE ====
===== Allgemeines =====
Das Modul {{Link2CmdRef|Anker=MQTT_GENERIC_BRIDGE|Lang=en|Label=MQTT_GENERIC_BRIDGE}} ermöglicht es, sein jeweiliges IO-Modul-Gerät zu nutzen, um diesen Kommunikationsweg für beliebig viele andere FHEM-Geräte bereitzustellen. Dabei erfolgt am MQTT_GENERIC_BRIDGE-Gerät selbst nur eine Basiskonfiguration, im Übrigen durch Attribute an dem jeweiligen Gerät selbst. So kann z.B. ein Aktor des Typs [[CUL_HM]] an- oder ausgeschaltet werden oder auch einfach nur seinen aktuellen Schaltzustand per MQTT-Protokoll publizieren.

Dieses Modul kann seit November 2018 mit allen drei IO-Modul-Varianten zusammen eingesetzt werden, also sowohl mit ''MQTT2_SERVER'' bzw. ''MQTT2_CLIENT'' oder ''MQTT'' (00_MQTT.pm). Für MQTT_GENERIC_BRIDGE wird allerdings auch bei Verwendung der MQTT2-IO's zusätzliche Software benötigt, insbesondere das Perl-Modul ''libmodule-pluggable-perl''<ref>Dieses kann über <code>apt-get install libmodule-pluggable-perl</code> installiert werden</ref>, damit im Hintergrund auch das Modul [[MQTT (Modul)|MQTT]] geladen werden kann. Damit gelten auch für diesen Modul die Installationsvoraussetzungen für [[MQTT#MQTT_.28Modul.29|MQTT]]!

===== MQTT_GENERIC_BRIDGE und autocreate bei MQTT2-IO-Modulen =====
Dabei sollte man jedoch beachten, dass eingehende MQTT-Nachrichten von den MQTT2-IO Modulen (''MQTT2_SERVER'' oder ''MQTT2_CLIENT'') nur dann an die ''MQTT_GENERIC_BRIDGE'' zur weiteren Auswertung übergeben werden, wenn entweder

- die ''autocreate''-Funktion des betreffenden IOs ausgeschaltet wird und bleibt, oder

- eine ''bridgeRegexp'' an einem beliebigen ''MQTT2_DEVICE'' existiert, die die betreffenden Nachrichten mit einer leeren CID zurückgibt.

Die technischen Hintergründe bzgl. autocreate sind diesem {{Link2Forum|Topic=95341|LinkText=Thread}} zu entnehmen.

Beispiel für die Erstellung einer passenden ''bridgeRegexp'':

Es existiert ein "Neben-FHEM" namens ''fhem2'', das von einem "Haupt-FHEM" namens ''fhem'' aus Nachrichten empfangen soll, die dann an die an ''fhem2'' angeschlossene Hardware weitergegeben werden. Die Nachrichten kommen über ein MQTT2_CLIENT-IO mit der CID ''fhem2'' in ''fhem2'' an. Das Haupt-FHEM sendet mit der ''$base'' ''fhem/''. Dann wäre in ''fhem2'' folgendes MQTT2_DEVICE anzulegen (der Name kann frei gewählt werden):
define M_G_B_bridgeRegex_device MQTT2_DEVICE fhem2
attr M_G_B_bridgeRegex_device bridgeRegexp [\b]fhem/.*:.* ""

===== Anwendungsbeispiele =====
Anwendungsfälle und -beispiele für das Modul sind diesem {{Link2Forum|Topic=91642|LinkText=Thread}} zu entnehmen.

==== MQTT_BRIDGE ====
Dieses Modul kann nur zusammen mit einem IO-Gerät des Typs [[MQTT (Modul)|MQTT]] verwendet werden. Dabei wird pro weiterzuleitendem anderen FHEM-Gerät eine eigene Instanz dieses Moduls verwendet. Auf den Einsatz dieser Option sollte in neuen Installationen zugunsten von ''MQTT_GENERIC_BRIDGE'' verzichtet werden.

==== Per publish-Befehl am IO-Gerät ====
Alle drei IO-Module kennen direkte ''publish''-Anweisungen, mit deren Hilfe beliebige ''payloads'' an beliebige ''topics'' gesendet werden können. Dies kann man z.B. in einem [[notify]] oder [[at]] nutzen, um einzelne Events zu publishen oder Werteanfragen abzusetzen.

Hier eine regelmäßige Werteabfrage auf einen [[EBUS-MQTT2|ebus]]:
defmod get_ebus_updates at +*00:15:00 set ebusMQTT publish ebusd/430/Hc1HeatCurve/get;
set ebusMQTT publish ebusd/430/HwcTempDesired/get;
...

==== RAW-Events am IO-Gerät (MQTT2.*) ====
Bei beiden MQTT2-IO-Modulen (MQTT2_SERVER und MQTT2_CLIENT) kann per [[Regulärer Ausdruck|regulärem Ausdruck]] festgelegt werden, welche Nachrichten ein Event erzeugen sollen, auf das dann wieder z.B. mit einem [[notify]] reagiert werden kann, z.B. um beliebige Schaltaktionen auszulösen.

== MQTT-Clients (Beispiele) ==

===Arduino-library===
Zur Kommunikation mit dem Broker von Seiten eines [[Arduino|Arduinos]] mit selbst erstellten Sketches böte sich der PubSubClient an.

===PC-Software===
Um die Funktionalität des Brokers zu testen kann z.B. ein Analyse-Tool wie MQTT.fx verwendet werden, oder die im Paket ''mosquitto-clients'' enthaltenen Linux-Kommandozeilen-Programme ''mosquitto_sub'' und ''mosquitto_pub''. Letzterer könnte z.E. auch aus beliebigen ''shell-scripten'' heraus aufgerufen werden. Als Perl-Bibliothek steht alternativ z.B. [https://metacpan.org/pod/distribution/AnyEvent-MQTT/bin/anyevent-mqtt-pub anyevent-mqtt-pub] zur Verfügung.

=== Tasmota ===
Eine derzeit oft genutzte Möglichkeit für MQTT bilden die [[Sonoff]]-Geräte und weitere [[ESP8266]]-basierte Hardware, die unter vielen Handelsnamen erhältlich sind. Werden diese mit Tasmota ('''T'''heo '''A'''rends '''S'''onoff '''M'''QTT '''O'''ver '''T'''he '''A'''ir - einer offenen Firmware von [https://github.com/arendst arendst]) geflasht, so kommunizieren sie über MQTT. Um diese Geräte einzubinden, ist wie folgt vorzugehen. Zuerst ist ein Serverdienst (Broker) bereitzustellen, wie oben beschrieben.

Unter Sonoff sind einige Topics voreingestellt. arendst stellt insbesondere drei Topic-Präfixe bereit, die seiner Meinung jedes Topic einleiten sollen (in den Eingabemasken als "%prefix%" notiert). Das sind einmal Kommandos (abgekürzt als cmnd), die dazu dienen, Befehle auszuführen. Daten werden mit tele und stat übertragen. Ein Topic besteht dann zuerst aus diesem Präfix und danach dem eigentlichen Topic. Wer also beispielsweise einem Sonoff_Switch einen Befehl senden will, sollte als Topic cmnd/Sonoff_Switch wählen. Wenn der Switch ein- und ausgeschaltet werden kann, muss der Topic noch das Wort POWER enthalten (in MQTT werden viele Kennworte komplett groß geschrieben). Der Topic lautet damit vollständig "cmnd/Sonoff_Switch/POWER/set"

{{Randnotiz|RNTyp=g|RNText=Dabei ist darauf zu achten, dass für den Parameter ''topic = %topic% (sonoff)'' statt ''sonoff'' ein gerätespezifischer eigener Name eingetragen wird. Hierzu kann man z.B. auch die dynamisch aus der Chip-ID erzeugte Kennung ''DVES_%06X'' verwenden, indem man die unter ''client (DVES_8BABA9)'' zu findende Angabe kopiert. Die eigentliche Umbenennung zu einem "sprechenden Namen" kann dann innerhalb von FHEM - mittels ''rename'' oder ggf. mit einem ''alias'' - erfolgen.}}

Link zum Forum: {{Link2Forum|Topic=27532|LinkText=MQTT FHEM Einrichtung}} (hier als ''MQTT_DEVICE''!):

### FHEM Device mit MQTT verbinden ###
define Sonoff_Switch MQTT_DEVICE
attr Sonoff_Switch IODev myBroker
attr Sonoff_Switch devStateIcon ON:rc_GREEN:OFF OFF:rc_RED:ON
attr Sonoff_Switch icon hue_filled_br30
attr Sonoff_Switch publishSet ON OFF cmnd/TestSwitch/POWER
attr Sonoff_Switch room MQTT
attr Sonoff_Switch subscribeReading_Licht stat/Sonoff_Switch/POWER
attr Sonoff_Switch subscribeReading_Sensor tele/Sonoff_Switch/SENSOR
attr Sonoff_Switch subscribeReading_Status stat/Sonoff_Switch/STATUS
attr Sonoff_Switch webCmd ON:OFF

Der hier dargestellte Beispielcode realisiert die Kommunikation zwischen FHEM und dem sonoff Modul via MQTT Broker. Zu beachten ist hier, dass '''subscribeReading_Licht''' und '''subscribeReading_Status''' unterschiedliche Syntax des Topic Strings haben!

=== OpenMQTTGateway ===
Um verschiedene Systeme wie BLE usw. auf MQTT zu bringen bietet sich OpenMQTTGateway an.

Ich habe es für BLE kompiliert und auf einem ESP32 installiert. Hierzu braucht man nur das blanke Board ohne Zusatzhardware.

Weiter infos hier: [https://github.com/1technophile/OpenMQTTGateway]

In FHEM wird das ganze über den eigenen Broker oder einen extern Broker (z.B.: Mosquitto) eingebunden.

Zusätzlich legt ihr noch ein Device hierzu an.

<code>define MQTT2_OMG1 MQTT2_DEVICE</code>

Ich habe es noch in den Raum MQTT2 geschoben.

Mit <code>set MQTT2_OMG1 attrTemplate OpenMQTTGateway_MCU</code> wird das Template festgelegt.

Aus diesem Device raus könnt ihr euch nun auch ein Dummy für z.B. einen MiFlora anlegen lassen. Das geschieht dann über <code>set MQTT2_OMG1 attrTemplate OpenMQTTGateway_BT_mi_flora_sensor</code>

== Sicherheit ==
Prinzipiell ist MQTT ebenso sicher wie eine Postkarte. Solange man es nicht extra absichert, kann jeder der, im eigenen LAN ist (und die Adresse vom Broker kennt) alle Topics mitlesen.
:<code>meinHaus/Flur/Haustuer:open / close</code>
bietet unter diesen Umständen reichlich Raum für Verbesserungen!

Abhilfe:
=== Username / Passwort ===
Zunächst kann man erst mal einen Username / Passwort vergeben, was alle IO-Device-Module unterstützen. Da ist zwar auch noch lange nicht sicher, aber zumindest steigert es den Aufwand schon mal. Jetzt muss man zumindest schon mal Pakete sniffen und verstehen, um unbefugt zu lesen oder gar zu publishen.

=== TLS ===
Um wirklich sicher zu werden, führt kein Weg an TLS vorbei.

Der MQTT-Client in [[#Tasmota|Tasmota]] (für ESP8266) kann mit TLS betrieben werden, vgl. [https://github.com/arendst/Tasmota/wiki/TLS Beschreibung im Tasmota-Wiki].

Leider kann z.B. ein Arduino das schlicht nicht mehr, da die einfacheren Modelle nicht über ausreichend Speicher und die Rechenleistung verfügen.

'''(Hier fehlt eine Anleitung für allowed usw.)'''

== Probleme ==
=== Anweisung und Ergebnis weichen voneinander ab ===
In der Regel melden MQTT-fähige Geräte entweder den Erhalt einer Nachricht zurück oder den Status nach Durchführung der in der ''payload'' enthaltenen Anweisung. Dabei findet aber in der Regel beim Empfänger eine Verarbeitung der Nachricht statt, ggf. wird diese auch weitergesendet und nochmals verarbeitet, bevor dann ggf. eine Rückmeldung des neuen Status an den MQTT-Server erfolgt. Handelt es sich um einfache on/off-Befehle, bleibt Anweisung und Ergebnis in der Regel identisch. Bei anderen, namentlich bei Dimmer-Werten, kann es zu Rundungsdifferenzen bei nummerischen Werten kommen. So kann z.B. ein Dimm-Wert von 70% gesetzt werden, zürückgemeldet wird dann aber 72% (oder 67%).
Dies ist technisch bedingt, vermeiden kann das jedoch in aller Regel nur der Autor der jeweiligen software/firmware auf dem "rechnenden" Gerät.

=== Unbeabsichtigte Schleifen ===
Durch Fehler in der topic-Struktur können unbeabsichtigte Schleifen entstehen, die FHEM komplett blockieren können. Es ist unbedingt darauf zu achten, dass die jeweiligen Sende- und Empfangs-topics andere sind!

== FAQ ==
=== Welche Infos sollten Anfragen im MQTT-Forum enthalten? ===
* Anfragen bitte nur zur aktuellsten FHEM-Version: Befehl <code>update</code> ergibt Ausgabe "nothing to do..."
* detaillierte Beschreibung des Problems
* Art der Einbindung
** eingesetzter MQTT-Server? (=> MQTT2_SERVER oder externer Serverdienst wie mosquitto?)
** Wenn externer Server: Interface-Modul: MQTT2_CLIENT oder 00_MQTT.pm?
** Bitte einen Hinweis, falls MQTT_GENERIC_BRIDGE definiert ist bzw. auch ein list von der MQTT_GENERIC_BRIDGE.
** TYPE des eigentlichen MQTT-Devices (MQTT2_DEVICE, MQTT_DEVICE, TASMOTA_DEVICE, ...)
* Informationen zur eigentlichen Komponente:
** Hersteller, ggf. aktuell verwendete firmware incl. Version (Beispiel: ein Shelly-Gerät mit originaler firmware verhält sich anders als dasselbe Gerät mit Tasmota-, ESPEasy oder ESPurna-firmware!).
** Bei weniger gängigen Komponenten oder Diensten:
*** (sofern vorhanden): Link zu Projektseiten, MQTT-API-Seiten usw..
*** Mittschnitte des MQTT-Verkehrs (z.B. durch Einschalten der rawEvents an den MQTT2-Interface-Modulen, s.o.).
** Ein ''list'' des eigentlichen Devices - bei MQTT2_DEVICE gerne in Form einer RAW-Definition (''list -r <devicename>'').
* Bei MQTT2-Einbindung und aktiviertem ''autocreate'' an den Interface-Modulen den Status des ''autocreate''-'Devices:
list TYPE=autocreate
=== Älterer FAQ-Thread im Forum ===
Dieser ist {{Link2Forum|Topic=70119|LinkText=hier}} zu finden. Bitte beachten: es sind einige grundlegende Informationen und Links zu vielen Tools und Fundstellen enthalten, allerdings nur bis zum Stand des Jahres 2017. Die neue Modulgeneration MQTT2_.* wird dort nicht behandelt.

== Links ==
* [http://mqtt.org Offizielle Homepage von MQTT, englisch]
* [http://www.hivemq.com/blog/mqtt-essentials-part-1-introducing-mqtt Sehr gute Einführung, englisch, sind 5 lesenswerte Teile]
* [https://www.heise.de/developer/artikel/MQTT-Protokoll-fuer-das-Internet-der-Dinge-2168152.html Ein Exkurs von Heise mit Beispielen, deutsch, sehr lesenswert]
* [http://www.mqttfx.org/ MQTT FX - ein sehr praktisches Analysetool]
* {{Link2Forum|Topic=69230|LinkText=Diskussionsthread im Forum}}
* {{Link2Forum|Topic=92888|LinkText=Thread, zur Entstehungsgeschichte von MQTT2_CLIENT}}
* {{Link2Forum|Topic=93255|LinkText=Ankündigungsthread zur MQTT2-Erweiterung der MQTT_GENERIC_BRIDGE}}
* [[MQTT_Einf%C3%BChrung_Teil_2|Teil 2 der MQTT Einführung]]: Detailaspekte (vorrangig zur Modulfamilie MQTT/MQTT_DEVICE)
* [[MQTT Einführung Teil 3|Teil 3 der MQTT Einführung]]: Arduino-Client selbst programmieren

== Hinweise ==
<references />

[[Kategorie:Glossary]]
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT|Einführung]]
[[Kategorie:MQTT| ]]

CPAN

2020-06-13T18:23:59Z

ChristophMorrison: Typo fix

= CPAN =

Das CPAN, Comprehensive Perl Archive Network, ist ein weltweit verteiltes Netzwerk für Perl-Module, das seit 1995 besteht und aktuell etwa 200 000 Module umfasst.

Siehe auch hier eine [https://www.cpan.org/modules/INSTALL.html Zusammenfassung des CPAN-Projektes].

== Clients ==

=== Plattformunabhängig ===

Das CPAN bietet drei plattformunabhängige Clients an, von denen zwei hier beschrieben werden. Die ''Empfehlung'' ist, <code>cpanm</code> zu nutzen.

==== cpanminus ====

[https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm cpanminus] (<code>cpanm</code>) ist der bevorzugte Weg, wie CPAN-Pakete installiert werden sollten. cpan-minus ist, wie <code>cpan</code> ein CPAN-Paket, das aber auch für viele Betriebssystem als fertiges Paket portiert wurde.

cpan-minus bietet einen [http://cpanmin.us/ Quickstart] an, der auf jedem System läuft, auf dem Perl installiert ist. Dazu muss folgender Befehl auf der Kommandozeile ausgeführt werden:

<pre>curl -L https://cpanmin.us | perl - App::cpanminus</pre>
Aus Sicherheitsgründen sollte vor Ausführung des Befehls überprüft werden, was unter [http://cpanmin.us/ cpanmin.us] zu finden ist, da ggf. Schadcode unbemerkt eingeschmuggelt werden könnte.

Ist der Client <code>cpanm</code> installiert, kann mit

<pre>cpanm Paket::Name</pre>
ein Paket (in diesem Falle das nicht-existende Paket <code>Paket::Name</code>) installiert werden. Die Option <code>--sudo</code> sorgt dafür, dass cpanminus die Installation als Superuser versucht (ggf. muss ein Passwort eingegeben werden).

==== Exkurs: cpan-outdated ====

Das Paket [https://metacpan.org/pod/distribution/cpan-outdated/script/cpan-outdated <code>cpan-outdated</code>] erzeugt eine cpanminus-kompatible Liste an CPAN-Paketen, die aktualisiert werden können, z.B.

<pre>$ cpan-outdated
A/AN/ANDK/CPAN-2.27.tar.gz
L/LE/LEONT/Test-Harness-3.42.tar.gz
B/BI/BINGOS/Archive-Tar-2.36.tar.gz
T/TO/TODDR/autodie-2.32.tar.gz
R/RU/RURBAN/B-Debug-1.26.tar.gz
I/IL/ILMARI/bareword-filehandles-0.007.tar.gz
P/PJ/PJACKLAM/bignum-0.51.tar.gz
X/XS/XSAWYERX/Carp-1.50.tar.gz
L/LE/LEEJO/CGI-4.47.tar.gz
A/AT/ATOOMIC/Clone-0.45.tar.gz
M/ML/MLEHMANN/common-sense-3.75.tar.gz
P/PM/PMQS/Compress-Raw-Bzip2-2.093.tar.gz
P/PM/PMQS/Compress-Raw-Zlib-2.093.tar.gz
P/PM/PMQS/IO-Compress-2.093.tar.gz
H/HM/HMBRAND/Config-Perl-V-0.31.tgz
A/AT/ATOOMIC/TimeDate-2.33.tar.gz
P/PM/PMQS/DB_File-1.853.tar.gz
H/HU/HURRICUP/Devel-Camelcadedb-v2019.1.tar.gz
P/PJ/PJCJ/Devel-Cover-1.36.tar.gz
A/AT/ATOOMIC/Devel-PPPort-3.58.tar.gz
M/MS/MSHELOR/Digest-SHA-6.02.tar.gz
R/RJ/RJBS/Email-Sender-1.300034.tar.gz</pre>
Sehr nützlich ist die Kombination aus cpanminus und cpan-outdated:

<pre>cpan-outdated | cpanm --sudo</pre>
Diese Befehlssequenz aktualisiert alle aktualisierbaren CPAN-Pakete mit Hilfe von cpanminus (als Superuser).

==== cpan ====

[https://metacpan.org/pod/CPAN <code>cpan</code>] ist der mit jeder Perl-Installation mitgelieferte Client für das CPAN und lässt sich entweder mit

<pre>perl -MCPAN -e shell</pre>
oder

<pre>cpan</pre>
starten. Es wird ein interaktiver Client gestartet; mit <code>h</code> kann eine sehr umfangreiche Hilfe aufgerufen werden.

Ein Modul lässt sich am einfachsten mit

<pre>cpan install PAKET::NAME</pre>
installieren (hier das nicht-existente Paket <code>PAKET::NAME</code>). <code>cpan</code> eignet sich weniger gut um Module zu installieren oder zu aktualisieren, aber sehr gut um nach Paketen zu suchen:

<pre>i /JSON/</pre>
findet jedes Paket, das die Zeichenkette <code>JSON</code> im Bereich Autor, Bundle, Distribution oder Modul enthält. Das sind meist viele Ergebnisse, aber liefert einen Überblick "was geht".

Erfahrungsgemäß ist <code>cpan</code> recht störrisch in der Handhabung. Deshalb empfehle ich die Nutzung von cpanminus.

=== OS-Paketmanager ===

==== Debian und Derivate (Ubuntu, Raspbian, etc.) ====

Vom Debian-Projekt werden viele, aber lange nicht alle, Pakete des CPAN auch als Pakete für den eingebauten Paketmanager <code>apt</code> [https://packages.debian.org/stable/perl/ bereitsgestellt]. Dort sind momentan etwa 4 000 Pakete verfügbar, d.h. rund 2% der im CPAN verfügbaren Pakete. Es ist nicht immer trivial, ein Paket zu finden. Ein einfacher Fall ist z.B. das Paket <code>Readonly</code>, der über <code>cpanm Readonly</code> oder <code>apt-get install libreadonly-perl</code> installiert werden könnte. Im Allgemeinen kann man sagen, dass sich der Name des <code>apt</code>-Paketes aus dem Prefix <code>lib</code>, gefolgt vom Paketnamen in Kleinbuchstaben, bei dem die <code>::</code> durch <code>-</code> ersetzt wurden, und dem Suffix <code>-perl</code> zusammensetzt:

{|
! CPAN
! Debian-Paket
|-
| Rose::URI
| librose-uri-perl
|-
| Sah::Schemas::Rinci
| libsah-schemas-rinci-perl
|}

Kein Beispiel wäre vollständig ohne Ausnahme, z.B.:

[https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>libromana-perligata-perl</code>] installiert das Perl-Paket [https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>Lingua::Romana::Perligata</code>], müsste nach der selbstgewählten Konvention aber <code>liblingua-romana-perligata-perl</code> heißen.

Vorteilhaft ist, dass man die Pakete zusammen mit anderen Debian-Paketen automatisch auf dem aktuellen Stand halten kann, z.B. [https://wiki.debian.org/UnattendedUpgrades <code>unattended-upgrades</code>] - man spart so eine doppelte Implementierung der Updates.

Wiederum von Nachteil ist, dass man mit einer auf ein Release festgelegten Quelle irgendwann auch keine Updates der Perl-Pakete mehr erhält.

==== SuSE Linux ====

YaST bietet aktuell etwa 3 121 der rund 200 000 Pakete in [https://build.opensuse.org/project/show/devel:languages:perl <code>devel:languages:perl</code>] an, dazu kommen noch einige Community-Pakete mit einer trivial nicht feststellbaren Anzahl an Paketen. Im Paket [https://build.opensuse.org/package/show/devel:languages:perl:CPAN-A/perl-App-cpanminus <code>perl-App-cpanminus</code>] ist <code>cpanm</code> enthalten.

==== RedHat Linux ====

==== MacOS ====

Für MacOS gilt, dass das installierte Perl den <code>cpan</code>-Client und eine Auswahl an Module mitbringt. <code>cpanm</code> lässt sich installieren und sollte auch der Weg der Wahl sein. Es ist außerdem möglich, Pakete über [https://www.macports.org/ MacPorts] zu installieren. MacPorts bietet noch weniger Pakete (aktuell 1 797 für Perl 5.26, 1 799 für Perl 5.28) als Debian.

==== Windows ====

[https://www.activestate.com/products/perl/downloads/ ActiveState] bietet eine Perl-Distribution an, die bereits mit einigen Module, 214 bei [https://platform.activestate.com/ActiveState/ActivePerl-5.28 Perl 5.28], ausgeliefert wird.

== Empfohlene Pakete ==

Im FHEM-Umfeld werden aktuell rund 120 CPAN-Pakete (mit Sub-Paketen) eingesetzt die keine [https://www.perl.com/article/what-is-the-perl-core-/ Core-Module] sind und ggf. für ein FHEM-Modul [[Meta|nachinstalliert]] werden müssen:

* Authen::OATH
* AutoLoader
* B
* Carp
* Color
* Compress::Zlib
* Convert::Base32
* Cpanel::JSON::XS
* Crypt::Argon2
* Crypt::CBC
* Crypt::Cipher::AES
* Crypt::ECB
* Crypt::Mode::CBC
* Crypt::MySQL
* Crypt::NaCl::Sodium
* Crypt::Rijndael
* Crypt::Rijndael_PP
* Crypt::URandom
* DBI
* DBI::Const::GetInfoType
* Data::Dumper
* Data::UUID
* Date::Parse
* DateTime
* Device::Firmata
* Device::Firmata::Base
* Device::Firmata::Constants
* Device::Firmata::Error
* Device::Firmata::Language
* Device::Firmata::Platform
* Device::Firmata::Protocol
* Device::SerialPort
* Device::USB
* Digest::CRC
* Digest::SHA1
* Encode::Detect::Detector
* Expect
* File::HomeDir
* HTML::Entities
* HTML::Parser
* HTTP::Cookies
* HTTP::Daemon
* HTTP::Headers
* HTTP::Request
* HTTP::Request::Common
* IO::Interface::Simple
* IO::Socket::Multicast
* IO::Socket::Multicast6
* IO::Socket::SSL
* IO::Socket::Timeout
* IO::String
* Image::ExifTool
* Image::LibRSVG
* Image::Size
* Inline
* JSON
* JSON::MaybeXS
* JSON::XS
* JSON::backportPP
* JsonMod::JSON::Path::Node
* LWP
* LWP::Simple
* LWP::UserAgent~6
* Linux::Inotify2
* LiquidCrystal
* Lirc::Client
* List::MoreUtils
* MIME::Lite
* MP3::Info
* MP3::Tag
* MP3::Tag::CDDB_File
* MP3::Tag::Cue
* MP3::Tag::File
* MP3::Tag::ID3v1
* MP3::Tag::ID3v2
* MP3::Tag::ImageExifTool
* MP3::Tag::ImageSize
* MP3::Tag::Inf
* MP3::Tag::LastResort
* MP3::Tag::ParseData
* Mail::IMAPClient
* Mojolicious~5.54
* Net::Address::IP::Local
* Net::Bonjour
* Net::FTPSSL
* Net::Jabber
* Net::MQTT::Constants
* Net::MQTT::Message
* Net::MQTT::Message::JustMessageId
* Net::Rendezvous
* Net::SIP
* Net::SIP::Packet
* Net::SMTP::SSL
* Net::Telnet
* Net::UPnP::AV::MediaRenderer
* Net::UPnP::AV::MediaServer
* Net::UPnP::ControlPoint
* Net::UPnP::Device
* Net::UPnP::Service
* Net::XMPP::Namespaces
* Nmap::Parser
* Path::Tiny
* Paws::Polly
* Perl::PrereqScanner::NotQuiteLite
* RPC::XML::Client
* RPC::XML::Server
* RiveScript
* SOAP::Lite
* Text::Iconv
* Try::Tiny
* UPnP::Common
* UPnP::ControlPoint
* URI::Escape
* WWW::Jawbone::Up
* Win32::SerialPort
* XML::LibXML
* XML::Parser::Lite

[https://raw.githubusercontent.com/fhem/doc-wiki/master/DE/Howtos/fhem-cpan-modules.txt Liste als plain text], z.B. um sie bei einer automatisierten Installation verwenden zu können. Die Liste wurde mit <code>Perl::PrereqScanner</code> aus dem <code>FHEM/</code>-Verzeichnis erstellt, durch <code>Core::List</code> gefiltert und mit <code>cpanm</code> auf Nicht-CPAN-Module (z.B. <code>FHEM::Meta</code> oder <code>DevIO</code>) geprüft.

[[Kategorie:HOWTOS]]
[[Kategorie:Systemadministration]]
[[Kategorie:Perl]]

CPAN

2020-06-13T18:21:59Z

ChristophMorrison:

= CPAN =

Das CPAN, Comprehensive Perl Archive Network, ist ein weltweit verteiltes Netzwerk für Perl-Module, das seit 1995 besteht und aktuell etwa 200 000 Module umfasst.

Siehe auch hier eine [https://www.cpan.org/modules/INSTALL.html Zusammenfassung des CPAN-Projektes].

== Clients ==

=== Plattformunabhängig ===

Das CPAN bietet drei plattformunabhängige Clients an, von denen zwei hier beschrieben werden. Die ''Empfehlung'' ist, <code>cpanm</code> zu nutzen.

==== cpanminus ====

[https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm cpanminus] (<code>cpanm</code>) ist der bevorzugte Weg, wie CPAN-Pakete installiert werden sollten. cpan-minus ist, wie <code>cpan</code> ein CPAN-Paket, das aber auch für viele Betriebssystem als fertiges Paket portiert wurde.

cpan-minus bietet einen [http://cpanmin.us/ Quickstart] an, der auf jedem System läuft, auf dem Perl installiert ist. Dazu muss folgender Befehl auf der Kommandozeile ausgeführt werden:

<pre>curl -L https://cpanmin.us | perl - App::cpanminus</pre>
Aus Sicherheitsgründen sollte vor Ausführung des Befehls überprüft werden, was unter [http://cpanmin.us/ cpanmin.us] zu finden ist, da ggf. Schadcode unbemerkt eingeschmuggelt werden könnte.

Ist der Client <code>cpanm</code> installiert, kann mit

<pre>cpanm Paket::Name</pre>
ein Paket (in diesem Falle das nicht-existende Paket <code>Paket::Name</code>) installiert werden. Die Option <code>--sudo</code> sorgt dafür, dass cpanminus die Installation als Superuser versucht (ggf. muss ein Passwort eingegeben werden).

==== Exkurs: cpan-outdated ====

Das Paket [https://metacpan.org/pod/distribution/cpan-outdated/script/cpan-outdated <code>cpan-outdated</code>] erzeugt eine cpanminus-kompatible Liste an CPAN-Paketen, die aktualisiert werden können, z.B.

<pre>$ cpan-outdated
A/AN/ANDK/CPAN-2.27.tar.gz
L/LE/LEONT/Test-Harness-3.42.tar.gz
B/BI/BINGOS/Archive-Tar-2.36.tar.gz
T/TO/TODDR/autodie-2.32.tar.gz
R/RU/RURBAN/B-Debug-1.26.tar.gz
I/IL/ILMARI/bareword-filehandles-0.007.tar.gz
P/PJ/PJACKLAM/bignum-0.51.tar.gz
X/XS/XSAWYERX/Carp-1.50.tar.gz
L/LE/LEEJO/CGI-4.47.tar.gz
A/AT/ATOOMIC/Clone-0.45.tar.gz
M/ML/MLEHMANN/common-sense-3.75.tar.gz
P/PM/PMQS/Compress-Raw-Bzip2-2.093.tar.gz
P/PM/PMQS/Compress-Raw-Zlib-2.093.tar.gz
P/PM/PMQS/IO-Compress-2.093.tar.gz
H/HM/HMBRAND/Config-Perl-V-0.31.tgz
A/AT/ATOOMIC/TimeDate-2.33.tar.gz
P/PM/PMQS/DB_File-1.853.tar.gz
H/HU/HURRICUP/Devel-Camelcadedb-v2019.1.tar.gz
P/PJ/PJCJ/Devel-Cover-1.36.tar.gz
A/AT/ATOOMIC/Devel-PPPort-3.58.tar.gz
M/MS/MSHELOR/Digest-SHA-6.02.tar.gz
R/RJ/RJBS/Email-Sender-1.300034.tar.gz</pre>
Sehr nützlich ist die Kombination aus cpanminus und cpan-outdated:

<pre>cpan-outdated | cpanm --sudo</pre>
Diese Befehlssequenz aktualisiert alle aktualisierbaren CPAN-Pakete mit Hilfe von cpanminus (als Superuser).

==== cpan ====

[https://metacpan.org/pod/CPAN <code>cpan</code>] ist der mit jeder Perl-Installation mitgelieferte Client für das CPAN und lässt sich entweder mit

<pre>perl -MCPAN -e shell</pre>
oder

<pre>cpan</pre>
starten. Es wird ein interaktiver Client gestartet; mit <code>h</code> kann eine sehr umfangreiche Hilfe aufgerufen werden.

Ein Modul lässt sich am einfachsten mit

<pre>cpan install PAKET::NAME</pre>
installieren (hier das nicht-existente Paket <code>PAKET::NAME</code>). <code>cpan</code> eignet sich weniger gut um Module zu installieren oder zu aktualisieren, aber sehr gut um nach Paketen zu suchen:

<pre>i /JSON/</pre>
findet jedes Paket, das die Zeichenkette <code>JSON</code> im Bereich Autor, Bundle, Distribution oder Modul enthält. Das sind meist viele Ergebnisse, aber liefert einen Überblick "was geht".

Erfahrungsgemäß ist <code>cpan</code> recht störrisch in der Handhabung. Deshalb empfehle ich die Nutzung von cpanminus.

=== OS-Paketmanager ===

==== Debian und Derivate (Ubuntu, Raspbian, etc.) ====

Vom Debian-Projekt werden viele, aber lange nicht alle, Pakete des CPAN auch als Pakete für den eingebauten Paketmanager <code>apt</code> [https://packages.debian.org/stable/perl/ bereitsgestellt]. Dort sind momentan etwa 4 000 Pakete verfügbar, d.h. rund 2% der im CPAN verfügbaren Pakete. Es ist nicht immer trivial, ein Paket zu finden. Ein einfacher Fall ist z.B. das Paket <code>Readonly</code>, der über <code>cpanm Readonly</code> oder <code>apt-get install libreadonly-perl</code> installiert werden könnte. Im Allgemeinen kann man sagen, dass sich der Name des <code>apt</code>-Paketes aus dem Prefix <code>lib</code>, gefolgt vom Paketnamen in Kleinbuchstaben, bei dem die <code>::</code> durch <code>-</code> ersetzt wurden, und dem Suffix <code>-perl</code> zusammensetzt:

{|
! CPAN
! Debian-Paket
|-
| Rose::URI
| librose-uri-perl
|-
| Sah::Schemas::Rinci
| libsah-schemas-rinci-perl
|}

Kein Beispiel wäre vollständig ohne Ausnahme, z.B.:

[https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>libromana-perligata-perl</code>] installiert das Perl-Paket [https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>Lingua::Romana::Perligata</code>], müsste nach der selbstgewählten Konvention aber <code>liblingua-romana-perligata-perl</code> heißen.

Vorteilhaft ist, dass man die Pakete zusammen mit anderen Debian-Paketen automatisch auf dem aktuellen Stand halten kann, z.B. [https://wiki.debian.org/UnattendedUpgrades <code>unattended-upgrades</code>] - man spart so eine doppelte Implementierung der Updates.

Wiederum von Nachteil ist, dass man mit einer auf ein Release festgelegten Quelle irgendwann auch keine Updates der Perl-Pakete mehr enthält.

==== SuSE Linux ====

YaST bietet aktuell etwa 3 121 der rund 200 000 Pakete in [https://build.opensuse.org/project/show/devel:languages:perl <code>devel:languages:perl</code>] an, dazu kommen noch einige Community-Pakete mit einer trivial nicht feststellbaren Anzahl an Paketen. Im Paket [https://build.opensuse.org/package/show/devel:languages:perl:CPAN-A/perl-App-cpanminus <code>perl-App-cpanminus</code>] ist <code>cpanm</code> enthalten.

==== RedHat Linux ====

==== MacOS ====

Für MacOS gilt, dass das installierte Perl den <code>cpan</code>-Client und eine Auswahl an Module mitbringt. <code>cpanm</code> lässt sich installieren und sollte auch der Weg der Wahl sein. Es ist außerdem möglich, Pakete über [https://www.macports.org/ MacPorts] zu installieren. MacPorts bietet noch weniger Pakete (aktuell 1 797 für Perl 5.26, 1 799 für Perl 5.28) als Debian.

==== Windows ====

[https://www.activestate.com/products/perl/downloads/ ActiveState] bietet eine Perl-Distribution an, die bereits mit einigen Module, 214 bei [https://platform.activestate.com/ActiveState/ActivePerl-5.28 Perl 5.28], ausgeliefert wird.

== Empfohlene Pakete ==

Im FHEM-Umfeld werden aktuell rund 120 CPAN-Pakete (mit Sub-Paketen) eingesetzt die keine [https://www.perl.com/article/what-is-the-perl-core-/ Core-Module] sind und ggf. für ein FHEM-Modul [[Meta|nachinstalliert]] werden müssen:

* Authen::OATH
* AutoLoader
* B
* Carp
* Color
* Compress::Zlib
* Convert::Base32
* Cpanel::JSON::XS
* Crypt::Argon2
* Crypt::CBC
* Crypt::Cipher::AES
* Crypt::ECB
* Crypt::Mode::CBC
* Crypt::MySQL
* Crypt::NaCl::Sodium
* Crypt::Rijndael
* Crypt::Rijndael_PP
* Crypt::URandom
* DBI
* DBI::Const::GetInfoType
* Data::Dumper
* Data::UUID
* Date::Parse
* DateTime
* Device::Firmata
* Device::Firmata::Base
* Device::Firmata::Constants
* Device::Firmata::Error
* Device::Firmata::Language
* Device::Firmata::Platform
* Device::Firmata::Protocol
* Device::SerialPort
* Device::USB
* Digest::CRC
* Digest::SHA1
* Encode::Detect::Detector
* Expect
* File::HomeDir
* HTML::Entities
* HTML::Parser
* HTTP::Cookies
* HTTP::Daemon
* HTTP::Headers
* HTTP::Request
* HTTP::Request::Common
* IO::Interface::Simple
* IO::Socket::Multicast
* IO::Socket::Multicast6
* IO::Socket::SSL
* IO::Socket::Timeout
* IO::String
* Image::ExifTool
* Image::LibRSVG
* Image::Size
* Inline
* JSON
* JSON::MaybeXS
* JSON::XS
* JSON::backportPP
* JsonMod::JSON::Path::Node
* LWP
* LWP::Simple
* LWP::UserAgent~6
* Linux::Inotify2
* LiquidCrystal
* Lirc::Client
* List::MoreUtils
* MIME::Lite
* MP3::Info
* MP3::Tag
* MP3::Tag::CDDB_File
* MP3::Tag::Cue
* MP3::Tag::File
* MP3::Tag::ID3v1
* MP3::Tag::ID3v2
* MP3::Tag::ImageExifTool
* MP3::Tag::ImageSize
* MP3::Tag::Inf
* MP3::Tag::LastResort
* MP3::Tag::ParseData
* Mail::IMAPClient
* Mojolicious~5.54
* Net::Address::IP::Local
* Net::Bonjour
* Net::FTPSSL
* Net::Jabber
* Net::MQTT::Constants
* Net::MQTT::Message
* Net::MQTT::Message::JustMessageId
* Net::Rendezvous
* Net::SIP
* Net::SIP::Packet
* Net::SMTP::SSL
* Net::Telnet
* Net::UPnP::AV::MediaRenderer
* Net::UPnP::AV::MediaServer
* Net::UPnP::ControlPoint
* Net::UPnP::Device
* Net::UPnP::Service
* Net::XMPP::Namespaces
* Nmap::Parser
* Path::Tiny
* Paws::Polly
* Perl::PrereqScanner::NotQuiteLite
* RPC::XML::Client
* RPC::XML::Server
* RiveScript
* SOAP::Lite
* Text::Iconv
* Try::Tiny
* UPnP::Common
* UPnP::ControlPoint
* URI::Escape
* WWW::Jawbone::Up
* Win32::SerialPort
* XML::LibXML
* XML::Parser::Lite

[https://raw.githubusercontent.com/fhem/doc-wiki/master/DE/Howtos/fhem-cpan-modules.txt Liste als plain text], z.B. um sie bei einer automatisierten Installation verwenden zu können. Die Liste wurde mit <code>Perl::PrereqScanner</code> aus dem <code>FHEM/</code>-Verzeichnis erstellt, durch <code>Core::List</code> gefiltert und mit <code>cpanm</code> auf Nicht-CPAN-Module (z.B. <code>FHEM::Meta</code> oder <code>DevIO</code>) geprüft.

[[Kategorie:HOWTOS]] [[Kategorie:Systemadministration]] [[Kategorie:Perl]]

CPAN

2020-06-13T18:16:40Z

ChristophMorrison: Die Seite wurde neu angelegt: „Das CPAN, Comprehensive Perl Archive Network, ist ein weltweit verteiltes Netzwerk für Perl-Module, das seit 1995 besteht und aktuell etwa 200 000 Module umfa…“

Das CPAN, Comprehensive Perl Archive Network, ist ein weltweit verteiltes Netzwerk für Perl-Module, das seit 1995 besteht und aktuell etwa 200 000 Module umfasst.

Siehe auch hier eine [https://www.cpan.org/modules/INSTALL.html Zusammenfassung des CPAN-Projektes].
==Clients==
===Plattformunabhängig===
Das CPAN bietet drei plattformunabhängige Clients an, von denen zwei hier beschrieben werden. Die ''Empfehlung'' ist, <code>cpanm</code> zu nutzen.
====cpanminus====
[https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm cpanminus] (<code>cpanm</code>) ist der bevorzugte Weg, wie CPAN-Pakete installiert werden sollten. cpan-minus ist, wie <code>cpan</code> ein CPAN-Paket, das aber auch für viele Betriebssystem als fertiges Paket portiert wurde.

cpan-minus bietet einen [http://cpanmin.us/ Quickstart] an, der auf jedem System läuft, auf dem Perl installiert ist. Dazu muss folgender Befehl auf der Kommandozeile ausgeführt werden:<pre>curl -L https://cpanmin.us | perl - App::cpanminus</pre>Aus Sicherheitsgründen sollte vor Ausführung des Befehls überprüft werden, was unter [http://cpanmin.us/ cpanmin.us] zu finden ist, da ggf. Schadcode unbemerkt eingeschmuggelt werden könnte.

Ist der Client <code>cpanm</code> installiert, kann mit<pre>cpanm Paket::Name</pre>ein Paket (in diesem Falle das nicht-existende Paket <code>Paket::Name</code>) installiert werden. Die Option <code>--sudo</code> sorgt dafür, dass cpanminus die Installation als Superuser versucht (ggf. muss ein Passwort eingegeben werden).
====Exkurs: cpan-outdated====
Das Paket [https://metacpan.org/pod/distribution/cpan-outdated/script/cpan-outdated <code>cpan-outdated</code>] erzeugt eine cpanminus-kompatible Liste an CPAN-Paketen, die aktualisiert werden können, z.B.<pre>$ cpan-outdated
A/AN/ANDK/CPAN-2.27.tar.gz
L/LE/LEONT/Test-Harness-3.42.tar.gz
B/BI/BINGOS/Archive-Tar-2.36.tar.gz
T/TO/TODDR/autodie-2.32.tar.gz
R/RU/RURBAN/B-Debug-1.26.tar.gz
I/IL/ILMARI/bareword-filehandles-0.007.tar.gz
P/PJ/PJACKLAM/bignum-0.51.tar.gz
X/XS/XSAWYERX/Carp-1.50.tar.gz
L/LE/LEEJO/CGI-4.47.tar.gz
A/AT/ATOOMIC/Clone-0.45.tar.gz
M/ML/MLEHMANN/common-sense-3.75.tar.gz
P/PM/PMQS/Compress-Raw-Bzip2-2.093.tar.gz
P/PM/PMQS/Compress-Raw-Zlib-2.093.tar.gz
P/PM/PMQS/IO-Compress-2.093.tar.gz
H/HM/HMBRAND/Config-Perl-V-0.31.tgz
A/AT/ATOOMIC/TimeDate-2.33.tar.gz
P/PM/PMQS/DB_File-1.853.tar.gz
H/HU/HURRICUP/Devel-Camelcadedb-v2019.1.tar.gz
P/PJ/PJCJ/Devel-Cover-1.36.tar.gz
A/AT/ATOOMIC/Devel-PPPort-3.58.tar.gz
M/MS/MSHELOR/Digest-SHA-6.02.tar.gz
R/RJ/RJBS/Email-Sender-1.300034.tar.gz</pre>Sehr nützlich ist die Kombination aus cpanminus und cpan-outdated:<pre>cpan-outdated | cpanm --sudo</pre>Diese Befehlssequenz aktualisiert alle aktualisierbaren CPAN-Pakete mit Hilfe von cpanminus (als Superuser).
====cpan====
[https://metacpan.org/pod/CPAN <code>cpan</code>] ist der mit jeder Perl-Installation mitgelieferte Client für das CPAN und lässt sich entweder mit<pre>perl -MCPAN -e shell</pre>oder<pre>cpan</pre>starten. Es wird ein interaktiver Client gestartet; mit <code>h</code> kann eine sehr umfangreiche Hilfe aufgerufen werden.

Ein Modul lässt sich am einfachsten mit<pre>cpan install PAKET::NAME</pre>installieren (hier das nicht-existente Paket <code>PAKET::NAME</code>). <code>cpan</code> eignet sich weniger gut um Module zu installieren oder zu aktualisieren, aber sehr gut um nach Paketen zu suchen:<pre>i /JSON/</pre>findet jedes Paket, das die Zeichenkette <code>JSON</code> im Bereich Autor, Bundle, Distribution oder Modul enthält. Das sind meist viele Ergebnisse, aber liefert einen Überblick "was geht".

Erfahrungsgemäß ist <code>cpan</code> recht störrisch in der Handhabung. Deshalb empfehle ich die Nutzung von cpanminus.
===OS-Paketmanager===
====Debian und Derivate (Ubuntu, Raspbian, etc.)====
Vom Debian-Projekt werden viele, aber lange nicht alle, Pakete des CPAN auch als Pakete für den eingebauten Paketmanager <code>apt</code> [https://packages.debian.org/stable/perl/ bereitsgestellt]. Dort sind momentan etwa 4 000 Pakete verfügbar, d.h. rund 2% der im CPAN verfügbaren Pakete. Es ist nicht immer trivial, ein Paket zu finden. Ein einfacher Fall ist z.B. das Paket <code>Readonly</code>, der über <code>cpanm Readonly</code> oder <code>apt-get install libreadonly-perl</code> installiert werden könnte. Im Allgemeinen kann man sagen, dass sich der Name des <code>apt</code>-Paketes aus dem Prefix <code>lib</code>, gefolgt vom Paketnamen in Kleinbuchstaben, bei dem die <code>::</code> durch <code>-</code> ersetzt wurden, und dem Suffix <code>-perl</code> zusammensetzt:
{|
!CPAN
!Debian-Paket
|-
|Rose::URI
|librose-uri-perl
|-
|Sah::Schemas::Rinci
|libsah-schemas-rinci-perl
|}Kein Beispiel wäre vollständig ohne Ausnahme, z.B.:

[https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>libromana-perligata-perl</code>] installiert das Perl-Paket [https://metacpan.org/pod/distribution/Lingua-Romana-Perligata/lib/Lingua/Romana/Perligata.pm <code>Lingua::Romana::Perligata</code>], müsste nach der selbstgewählten Konvention aber <code>liblingua-romana-perligata-perl</code> heißen.

Vorteilhaft ist, dass man die Pakete zusammen mit anderen Debian-Paketen automatisch auf dem aktuellen Stand halten kann, z.B. [https://wiki.debian.org/UnattendedUpgrades <code>unattended-upgrades</code>] - man spart so eine doppelte Implementierung der Updates.

Wiederum von Nachteil ist, dass man mit einer auf ein Release festgelegten Quelle irgendwann auch keine Updates der Perl-Pakete mehr enthält.
====SuSE Linux====
YaST bietet aktuell etwa 3 121 der rund 200 000 Pakete in [https://build.opensuse.org/project/show/devel:languages:perl <code>devel:languages:perl</code>] an, dazu kommen noch einige Community-Pakete mit einer trivial nicht feststellbaren Anzahl an Paketen. Im Paket [https://build.opensuse.org/package/show/devel:languages:perl:CPAN-A/perl-App-cpanminus <code>perl-App-cpanminus</code>] ist <code>cpanm</code> enthalten.
====RedHat Linux====
====MacOS====
Für MacOS gilt, dass das installierte Perl den <code>cpan</code>-Client und eine Auswahl an Module mitbringt. <code>cpanm</code> lässt sich installieren und sollte auch der Weg der Wahl sein. Es ist außerdem möglich, Pakete über [https://www.macports.org/ MacPorts] zu installieren. MacPorts bietet noch weniger Pakete (aktuell 1 797 für Perl 5.26, 1 799 für Perl 5.28) als Debian.
====Windows====
[https://www.activestate.com/products/perl/downloads/ ActiveState] bietet eine Perl-Distribution an, die bereits mit einigen Module, 214 bei [https://platform.activestate.com/ActiveState/ActivePerl-5.28 Perl 5.28], ausgeliefert wird.
==Empfohlene Pakete==
Im FHEM-Umfeld werden aktuell rund 120 CPAN-Pakete (mit Sub-Paketen) eingesetzt die keine [https://www.perl.com/article/what-is-the-perl-core-/ Core-Module] sind und ggf. für ein FHEM-Modul [[Meta|nachinstalliert]] werden müssen:
*Authen::OATH
*AutoLoader
*B
*Carp
*Color
*Compress::Zlib
*Convert::Base32
*Cpanel::JSON::XS
*Crypt::Argon2
*Crypt::CBC
*Crypt::Cipher::AES
*Crypt::ECB
*Crypt::Mode::CBC
*Crypt::MySQL
*Crypt::NaCl::Sodium
*Crypt::Rijndael
*Crypt::Rijndael_PP
*Crypt::URandom
*DBI
*DBI::Const::GetInfoType
*Data::Dumper
*Data::UUID
*Date::Parse
*DateTime
*Device::Firmata
*Device::Firmata::Base
*Device::Firmata::Constants
*Device::Firmata::Error
*Device::Firmata::Language
*Device::Firmata::Platform
*Device::Firmata::Protocol
*Device::SerialPort
*Device::USB
*Digest::CRC
*Digest::SHA1
*Encode::Detect::Detector
*Expect
*File::HomeDir
*HTML::Entities
*HTML::Parser
*HTTP::Cookies
*HTTP::Daemon
*HTTP::Headers
*HTTP::Request
*HTTP::Request::Common
*IO::Interface::Simple
*IO::Socket::Multicast
*IO::Socket::Multicast6
*IO::Socket::SSL
*IO::Socket::Timeout
*IO::String
*Image::ExifTool
*Image::LibRSVG
*Image::Size
*Inline
*JSON
*JSON::MaybeXS
*JSON::XS
*JSON::backportPP
*JsonMod::JSON::Path::Node
*LWP
*LWP::Simple
*LWP::UserAgent~6
*Linux::Inotify2
*LiquidCrystal
*Lirc::Client
*List::MoreUtils
*MIME::Lite
*MP3::Info
*MP3::Tag
*MP3::Tag::CDDB_File
*MP3::Tag::Cue
*MP3::Tag::File
*MP3::Tag::ID3v1
*MP3::Tag::ID3v2
*MP3::Tag::ImageExifTool
*MP3::Tag::ImageSize
*MP3::Tag::Inf
*MP3::Tag::LastResort
*MP3::Tag::ParseData
*Mail::IMAPClient
*Mojolicious~5.54
*Net::Address::IP::Local
*Net::Bonjour
*Net::FTPSSL
*Net::Jabber
*Net::MQTT::Constants
*Net::MQTT::Message
*Net::MQTT::Message::JustMessageId
*Net::Rendezvous
*Net::SIP
*Net::SIP::Packet
*Net::SMTP::SSL
*Net::Telnet
*Net::UPnP::AV::MediaRenderer
*Net::UPnP::AV::MediaServer
*Net::UPnP::ControlPoint
*Net::UPnP::Device
*Net::UPnP::Service
*Net::XMPP::Namespaces
*Nmap::Parser
*Path::Tiny
*Paws::Polly
*Perl::PrereqScanner::NotQuiteLite
*RPC::XML::Client
*RPC::XML::Server
*RiveScript
*SOAP::Lite
*Text::Iconv
*Try::Tiny
*UPnP::Common
*UPnP::ControlPoint
*URI::Escape
*WWW::Jawbone::Up
*Win32::SerialPort
*XML::LibXML
*XML::Parser::Lite
[https://raw.githubusercontent.com/fhem/doc-wiki/master/DE/Howtos/fhem-cpan-modules.txt Liste als plain text], z.B. um sie bein einer automatisierten Installation verwenden zu können. Die Liste wurde mit <code>Perl::PrereqScanner</code> aus dem <code>FHEM/</code>-Verzeichnis erstellt, durch <code>Core::List</code> gefiltert und mit <code>cpanm</code> auf Nicht-CPAN-Module (z.B. <code>FHEM::Meta</code> oder <code>DevIO</code>) geprüft.

DevelopmentModuleIntro

2020-06-07T14:41:06Z

ChristophMorrison: Moved sub paragraph to a real one

{{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]]

HttpUtils

2020-05-22T12:04:54Z

ChristophMorrison: Nutzlose Prototypen entfernt

{{Infobox Modul
|ModPurpose=Hilfsfunktionen für HTTP-Zugriffe
|ModType=u
|ModForumArea=Automatisierung
|ModTechName=HttpUtils.pm
|ModOwner=rudolfkoenig ({{Link2FU|8|Forum}} / [[Benutzer Diskussion:Rudolfkoenig|Wiki]])
}}

Das Modul [[HttpUtils]](.pm) ist sowohl für Modulentwickler als auch für Endanwender gedacht, um Daten via HTTP auszutauschen. Es stellt dabei eine Reihe von Funktionen zur Verfügung und wird beispielsweise vom Modul [[HTTPMOD]] intensiv genutzt.

== Primäre Funktionen (HTTP) ==
Es ist zu beachten, dass bei den Funktionen
* <code>GetHttpFile()</code>
* <code>GetFileFromURL</code>
* <code>GetFileFromURLQuiet</code>
* <code>HttpUtils_BlockingGet</code>
ein sogenannter "blockierender" Aufruf durchgeführt wird. Das bedeutet, dass FHEM bei einem Aufruf einer dieser Funktionen solange wartet und dabei absolut nichts macht, bis die Antwort vom HTTP-Server eintrifft und die Funktion damit beendet ist. Das kann bei Verbindungsproblemen evtl. dazu führen, dass FHEM für die gesamte Wartezeit (Timeout) steht und nichts verarbeitet. Problematisch ist das gerade bei Anwendungen oder Hardware, die eine zeitnahe Reaktion von FHEM erwarten (z.B. HomeMatic-Geräte). In der Zeit, in der auf eine HTTP Antwort gewartet wird, steht FHEM dabei komplett.

Es wird daher empfohlen, die Funktionen so sparsam wie möglich zu verwenden und die Timeouts so niedrig wie möglich zu halten, um ein längeres Einfrieren von FHEM möglichst zu vermeiden.

Um eine Blockierung zu vermeiden wird generell die Verwendung von
:<code>HttpUtils_NonblockingGet</code>
empfohlen. Diese führt den HTTP-Request asynchron durch, wodurch ein Blockieren von FHEM verhindert wird. Wie das genau funktioniert, wird in dem entsprechenden Kapitel beschrieben.

=== GetHttpFile ===
Die Funktion GetHttpFile ist die denkbar einfachste Variante um eine URL aufzurufen.
:<code>GetHttpFile($server, $file)</code>
{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$server</code>'''

''mandatory''
|| Der DNS-Name oder die IP-Adresse des HTTP-Servers 
Beispiel:

* ''<nowiki>www.myhost.com</nowiki>''
* ''<nowiki>192.168.0.10</nowiki>''
|-
| style="vertical-align:top" | '''<code>$file</code>'''

''mandatory''
|| Die Datei, welche auf dem HTTP-Server aufgerufen werden soll. 
Beispiel:
* ''/''
* ''/index.html''
* ''/directory/image.jpg''
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form einer Zeichenkette.

=== GetFileFromURL ===
Die Funktion GetFileFromURL ruft die HTTP-URL auf und gibt als Funktionsergebnis den Seiteninhalt zurück. Im Gegensatz zu GetHttpFile beinhaltet GetFileFromURL einige Zusatzoptionen in Form von Funktionsparametern.

'''Aufruf: <code>GetFileFromURL($url, ''[$timeout], [$data], [$noshutdown], [$loglevel]'')</code>'''

{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$url</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. 
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Falls ein Username sowie Passwort übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen zu vermeiden.
|-
| style="vertical-align:top" | '''<code>$timeout</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" | '''<code>$data</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über $data übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$noshutdown</code>'''

''optional''
|| Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung, bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$loglevel</code>'''

''optional''
|| Das [[verbose|Loglevel]], in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

=== GetFileFromURLQuiet ===
Diese Funktion funktioniert ähnlich wie GetFileFromURL. Allerdings wird die tatsächliche URL in allen erzeugten Log-Meldungen unkenntlich gemacht um z.B. Zugangsdaten nicht preiszugeben. Die aufgerufene Seite wird ebenfalls als Funktionsergebnis zurückgegeben.

'''Aufruf: <code>GetFileFromURLQuiet($url, ''[$timeout], [$data], [$noshutdown], [$loglevel]'')</code>'''

{| class="wikitable"
|-
! Parameter!! Bedeutung
|-
| style="vertical-align:top" | '''<code>$url</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. 
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Falls ein Username sowie Passwort übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen zu vermeiden.
|-
| style="vertical-align:top" | '''<code>$timeout</code>'''

''optional''
|| Die maximale Dauer in Sekunden für die HTTP-Anfrage

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" | '''<code>$data</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über <code>$data</code> übergeben. Die Daten werden dabei als Formulardaten übertragen. Wenn man den Content-Type beeinflussen möchte, oder mehrere Formular-Felder senden möchte, sollte man zur Funktion HttpUtils_BlockingGet oder HttpUtils_NonblockingGet greifen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$noshutdown</code>'''

''optional''
|| Wenn $noshutdown auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung bevor, sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$loglevel</code>'''

''optional''
|| Das Loglevel, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|}

Funktionsergebnis ist der Inhalt der aufgerufenen Seite in Form eines Strings.

=== HttpUtils_BlockingGet ===
Wenn die bisher genannten Funktionen nicht ausreichen um die gewünschte Abfrage durchzuführen, so kann man diese Funktion verwenden. Aufgrund zahlreicher Parameter ermöglicht sie viele Anpassungsmöglichkeiten. Diese Funktion hat dabei nicht wie üblich eine Liste an Funktionsparametern, sondern lediglich einen Parameter, welcher eine Hashreferenz mit allen Funktionsparametern darstellt. Dieser Hash enthält sämtliche Parameter inkl. Werten.

'''Aufruf: <code>HttpUtils_BlockingGet($param)</code>'''

Der Parameter $param ist eine Referenz auf eine Hash-Struktur, welche die einzelnen Parameter enthält. Der Hash $param kann folgende Optionen beinhalten:

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| style="vertical-align:top" | '''<code>$param->{url}</code>'''

''mandatory''
|| Die HTTP-URL, welche aufgerufen werden soll. Diese kann optional Usernamen, Passwort und einen Port enthalten. Sowohl HTTP als auch HTTPS wird hierbei unterstützt. 
Beispiel:

* ''<nowiki>http://www.myhost.com/directory/</nowiki>''
* ''<nowiki>https://www.myhost.com/</nowiki>''
* ''<nowiki>http://www.myhost.com:8080/</nowiki>''
* ''<nowiki>http://user:password@www.myhost.com/</nowiki>''

'''WICHTIG:''' Alternativ können die Zugangsdaten auch in <code>$param->{user}</code> und <code>$param->{pwd}</code> übergeben werden. Falls Username und Passwort in der URL übergeben werden, so müssen diese vorher jeweils mittels [[#urlEncode|urlEncode()]] in URL-kompatible Form umgewandelt werden um Probleme mit evtl. enthaltenen Sonderzeichen (z.B. ":" und "@") zu vermeiden, da sonst die URL nicht mehr einer validen Syntax entspricht.
|-
| style="vertical-align:top" |'''<code>$param->{timeout}</code>'''

''optional''
|| Die maximale Dauer in Sekunden bis der Server eine Antwort liefern muss. Andernfalls wird der Request mit einer Fehlermeldung abgebrochen.

Beispiel: 5 ''(Sekunden)''

Standardwert: 4 Sekunden
|-
| style="vertical-align:top" |'''<code>$param->{data}</code>'''

''optional''
|| Wenn man Daten via HTTP-POST übertragen möchte, so kann man die Nutzdaten über <code>$param->{data}</code> übergeben. Die Daten werden dabei als Formulardaten übertragen. Die Daten können dabei auf zwei Arten übergeben werden:

1. Daten als Zeichenkette:
:* Die Daten werden komplett als gesamte Zeichenkette in <code>$param->{data}</code> abgelegt (z.B.: <code>$param->{data} = "Jede Menge tolle Daten"</code>).
2. Daten als Hash-Struktur:
:* Die Daten werden als Hash mit Key-Value-Pairs übergeben (z.B.: <code>$param->{data}{field1} = "value1", $param{data}{field2} = "value2", ...</code> ). Die Daten werden dann als Formulardaten mit mehrfachen Datenfeldern übertragen.

Standardwert: ''[leer]''

|-
| style="vertical-align:top" | '''<code>$param->{user}</code>'''

''optional''
||Im Falle einer notwendigen HTTP-Authentifizierung, der zu benutzende Username um sich gegenüber dem Server zu identifizieren. Alternativ kann der Username und das Passwort auch direkt in der URL mitgegeben werden (siehe jedoch <code>$param->{hideurl}</code>).

Standardwert: ''[leer]''
|-
| style="vertical-align:top" | '''<code>$param->{pwd}</code>'''

''optional''
||Im Falle einer notwendigen HTTP-Authentifizierung, das zu benutzende Passwort um sich gegenüber dem Server zu identifizieren. Alternativ kann der Username und das Passwort auch direkt in der URL mitgegeben werden (siehe jedoch <code>$param->{hideurl}</code>).
Standardwert: ''[leer]''
|-
| style="vertical-align:top" | '''<code>$param->{noshutdown}</code>'''

''optional''
||Wenn <code>$param->{noshutdown}</code> auf 1 gesetzt ist, wird dem HTTP-Server nicht implizit mitgeteilt, dass die Verbindung nach dem Request geschlossen werden soll. Viele Webserver schließen in solch einem Fall die Verbindung, bevor sie die Antwort senden. Bei 0 wird dem Webserver mitgeteilt, dass der Sendevorgang beendet ist und nun die Antwort abgewartet wird.

Standardwert: 1
|-
| style="vertical-align:top" | '''<code>$param->{loglevel}</code>'''

''optional''
|| Das Loglevel, in dem sämtliche Logmeldungen zu dieser HTTP-Abfrage erzeugt werden sollen.

Standardwert: 4
|-
| style="vertical-align:top" | '''<code>$param->{hideurl}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird die gesamte URL in sämtlichen Log-Ausgaben unkenntlich gemacht. Dies notwendig, wenn z.B. Zugangsdaten direkt in der URL angegeben wurden, oder die URL ein geheimes Token oder andere schützenswerte Informationen enthält.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{ignoreredirects}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, werden Umleitungen durch den Server ignoriert und der Request beendet. Dies kann erforderlich sein um evtl. Cookies aus der Antwort, welche eine Umleitung enthält aus dem HTTP Header zu extrahieren um diese im nächsten Request weiterzuverwenden.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{method}</code>'''

''optional''
||Die HTTP-Methode, welche zur Abfrage verwendet werden soll. Sofern keine Daten übertragen werden ist dies standardmäßig "GET", ansonsten "POST". Es können aber auch andere Methoden verwendet werden.

Standardwert: "GET"
|-
| style="vertical-align:top" | '''<code>$param->{keepalive}</code>'''

''optional''
||Wenn dieser Parameter auf 1 gesetzt ist, wird dem Server der Wunsch mitgeteilt, die Verbindung offen zu lassen für weitere Anfragen. Sobald die Antwort auf den jeweiligen Request eintrifft, bleibt die TCP-Verbindung bestehen (sofern der Server dies unterstützt). Anschließend kann man den Parameter-Hash mit einer neuen URL und Optionen füllen. Der Parameter "keepalive" sollte dabei weiterhin gesetzt bleiben, sofern die Verbindung auch weiterhin möglichst erhalten bleiben soll.

Um eine offene Verbindung endgültig zu schließen, muss die Funktion [[HttpUtils#HttpUtils_Close|HttpUtils_Close]] aufgerufen werden.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{header}</code>'''

''optional''
|| Eigene HTTP-Header-Zeilen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. den Content-Type festzulegen, oder einfach nur zusätzliche Header-Felder zu setzen. Es gibt zwei Möglichkeiten, diesen Parameter zu befüllen.

# Als '''Zeichenkette'''. Mehrere Header-Zeilen müssen dabei mit "\r\n" getrennt werden.
# Als '''Hash-Struktur'''. Hierbei findet eine Zuordnung von Header-Bezeichnung zum Wert als Key-Value-Pair statt.

Beispiel:
* <code>"User-Agent: Mozilla/1.22'''\r\n'''Content-Type: application/xml"</code>
* <code>"Content-Type: application/xml"</code>
* <code>{ "User-Agent" => "Mozilla/1.22", "Content-Type" => "application/xml" }</code>
* <code>{ "Content-Type" => "application/xml" }</code>

Standardwert: ''[leer]''
|-
| style="vertical-align:top" | '''<code>$param->{sslargs}</code>'''

''optional''
|| Eigene SSL-Optionen können über diesen Parameter eingebracht werden. Er kann dazu genutzt werden um z.B. die SSL-Zertifikats Verifikation abzuschalten. Die SSL-Optionen müssen als eigene Hash-Referenz übergeben werden. Eine Liste aller möglichen Optionen findet man in der Perl-Dokumentation zu [http://search.cpan.org/~sullr/IO-Socket-SSL-2.016/lib/IO/Socket/SSL.pod#Description_Of_Methods IO::Socket::SSL].

Beispiel:
* <code>$param->{sslargs} = { SSL_verify_mode => 0, sslOpt2 => 'sslVal2' }</code>

Standardwert: ''{ }''
|-
| style="vertical-align:top" | '''<code>$param->{httpversion}</code>'''

''optional''
|| Die HTTP-Version, welche zur Abfrage verwendet werden soll. Standardmäßig werden alle Abfragen mit HTTP/1.0 durchgeführt. Falls es jedoch notwendig ist HTTP/1.1 zu verwenden, so sollte <code>$param->{httpversion}</code> auf "1.1" gesetzt werden. Bei Version 1.1 wird automatisch der Header "<code>Connection: close</code>" implizit mitgesendet.

Standardwert: "1.0"
|-
| style="vertical-align:top" | '''<code>$param->{digest}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird bei vorhandenen Authentifizierungsdaten (Username+Passwort) eine Authentifizierung via Digest-Verfahren nach RFC 2617<ref name="rfc2617">RFC 2617 - HTTP Authentication: Basic and Digest Access Authentication</ref> erwartet. Die Anmeldedaten werden dann nur verwendet, wenn dieser explizit eine HTTP Digest Authentifizierung einleitet. Ist dieser Parameter nicht gesetzt (Wert: 0), wird bei vorhandenen Authentifizierungsdaten immer eine HTTP Basic<ref name="rfc2617" /> Authentifizierung im Request mitgeschickt.

Standardwert: 0
|-
| style="vertical-align:top" | '''<code>$param->{compress}</code>'''

''optional''
|| Wenn dieser Parameter den Wert 1 trägt, wird dem Server die Verwendung von Komprimierung in Form GZIP oder alternativ Deflate<ref>RFC 1951 - DEFLATE Compressed Data Format Specification version 1.3</ref> zur Übertragung der Antwort ermöglicht. Die komprimierte Antwort wird dabei direkt durch HttpUtils.pm wieder dekomprimiert. Wird dieser Parameter auf den Wert 0 gesetzt, so wird keine Komrpimierung ermöglicht.

'''WICHTIG''': Die Verwendung von Komprimierung in HttpUtils.pm kann mit dem globalen Attribut "httpcompress" (Standardwert: 1) durch setzen auf 0 für die gesamte FHEM Installation durch den Nutzer deaktiviert werden. In diesem Fall ist der Parameter <code>$param->{compress} = 1</code> wirkungslos.

Standardwert: 1
|}

Als Rückgabewert von HttpUtils_BlockingGet wird ein Array mit zwei Rückgabewerten zurückgegeben:
:<code>($err, $data) = HttpUtils_BlockingGet( … )</code>
Diese zwei Rückgabewerte haben folgende Bedeutung:

{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$err</code>'''|| Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.

Wenn kein Fehler aufgetreten ist, ist dieser Wert mit einem Leerstring gefüllt (<code>$err = ""</code>)
|-
| style="vertical-align:top" | '''<code>$data</code>'''|| Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben.

Falls ein Fehler aufgetreten ist, ist dieser Wert mit einem Leersting gefüllt (<code>$data = ""</code>)
|}

=== HttpUtils_NonblockingGet ===
{{Randnotiz|RNText=Die Funktion HttpUtils_NonblockingGet ist nicht komplett durchgehend "non-blocking". DNS-Abfragen sind weiterhin blockierend. Insbesondere wenn der DNS-Name nicht aufgelöst werden kann.}}
Diese Funktion arbeitet ähnlich wie HttpUtils_BlockingGet. Allerdings wird das Ergebnis nicht als Funktionsergebnis zurückgegeben. Die Funktion HttpUtils_NonblockingGet initiiert den Verbindungsaufbau und übergibt alles weitere an FHEM interne Routinen. Sobald eine Antwort vom HTTP-Server eintrifft, wird eine Callback-Funktion mit verschiedenen Parametern (unter anderem auch das Ergebnis) aufgerufen, um die Antwort entgegenzunehmen und weiter zu verarbeiten.

Der Aufruf ist daher ähnlich zu HttpUtils_BlockingGet mit nur einem Parameter-Hash:

'''Aufruf: <code>HttpUtils_NonblockingGet($param)</code>'''

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| colspan="2" style="text-align:center" | ''''' Alle Hash-Parameter, welche für HttpUtils_BlockingGet gelten, sind auch für HttpUtils_NonblockingGet gültig''''' 
|-
| style="vertical-align:top" | '''<code>$param->{callback}</code>'''

''mandatory''
|| Eine Funktion (oder eine Referenz auf eine Funktion), welche die Ergebnisdaten entgegennimmt und die Antwort entsprechend weiterverarbeitet. Die Callback-Funktion muss dabei 3 Parameter erwarten. Die Funktionsparameter der Callback-Funktion werden im nachfolgenden Abschnitt näher erläutert.

Beispiel:
* <code>$param->{callback} = \&MyCallbackFn</code> — ''(Referenzzeiger auf Funktionsname)''
* <code>$param->{callback} = sub(){ … }</code> — ''(direkte Funktionsdefinition)''
|-
| style="vertical-align:top;white-space:nowrap;" | '''<code>$param->{incrementalTimout}</code>'''

''optional''
|| Sofern gesetzt (Wert: <code>1</code>), wird der Timeout nach jedem Empfang von Teil-Daten wieder zurückgesetzt. So können größere Datenmengen von langsamen Sendern empfangen werden, ohne den Parameter <code>timeout</code> zu erhöhen und dadurch tatsächliche Verbindungsprobleme erst spät zu erkennen.

Standardwert: 0
|-
| style="vertical-align:top" | ''Benutzerdefinierte Parameter''
|| Es können im Hash weitere benutzerdefinierte Parameter gesetzt werden, welche evtl. in der Callback-Funktion benötigt werden, um die Antwort korrekt zu verarbeiten.

Zum Beispiel im Rahmen der Modul-Programmierung wäre das <code>$hash</code> der aktuellen Definition. Alle gesetzten Parameter sind in der Callback-Funktion wieder über <code>$param</code> direkt abrufbar und können ausgewertet werden.

Beispiel:
* <code>$param->{hash} = $hash</code>
* <code>$param->{command} = "on"</code>

|}

Ein Funktionsrückgabewert von HttpUtils_NonblockingGet existiert nicht, da die eigentliche Rückgabe der Daten über die Callback-Funktion erfolgt. Die Callback-Funktion wird aufgerufen, sobdald der HTTP-Request abgeschlossen ist, oder ein Fehler aufgetreten ist. Der Funktionsaufruf erfolgt mit den folgenden Parametern:

<code> ''MyCallbackFn'' ( $param, $err, $data )</code>

Diese 3 Parameter haben dabei folgende Bedeutung:

{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$param</code>''' || Der Parameter-Hash, mit allen Argumenten die beim Aufruf der Funktion übergeben worden sind.

Es ist möglich, dass der Parameter-Hash nach erfolgter Abfrage zusätzliche oder veränderte Elemente enthält:
* '''<code>$param->{redirects}</code>''' - Die Anzahl an Umleitungen die erfolgte, bis die Anfrage beantwortet wurde.
* '''<code>$param->{url}</code>''' - Die URL, die nach erfolgter Umleitung die Anfrage beantwortet hat.
* '''<code>$param->{protocol}</code>''' - Das verwendete Protokoll, welches zur Abfrage verwendet wurde ("http" oder "https").
* '''<code>$param->{path}</code>''' - Der Pfad, welcher auf dem HTTP-Server angefragt wurde.
* '''<code>$param->{host}</code>''' - Der Name oder die IP-Adresse des HTTP-Servers.
* '''<code>$param->{httpheader}</code>''' - Der gesamte HTTP Header, welcher der Server bei der letzten Antwort zurücklieferte.
* '''<code>$param->{code}</code>''' - Der HTTP-Statuscode, mit dem die Anfrage vom Server beantwortet wurde.
* '''<code>$param->{addr}</code>''' - Die HTTP-URL ohne Pfad und evtl. Authentifizerungsinformationen des HTTP-Servers (z.B. "<nowiki>http://myserver.com:8080</nowiki>").
* '''<code>$param->{auth}</code>''' - Ein Flag (0/1) ob Zugangsdaten für den Request zur Verfügung standen (durch Angabe in der URL oder direkt in <code>$param</code>).
|-
| style="vertical-align:top" | '''<code>$err</code>'''|| Falls beim Aufruf der URL ein Fehler aufgetreten ist (z.B. Server nicht erreichbar oder Verbindungstimeout), dann ist dieser Wert mit einer Fehlermeldung gefüllt.

Wenn kein Fehler aufgetreten ist, ist dieser Wert mit einem Leerstring gefüllt (<code>$err = ""</code>)
|-
| style="vertical-align:top" | '''<code>$data</code>'''|| Die Ergebnisdaten, welche der HTTP-Server zurückgeliefert hat. Die Daten werden als Klartext in Form eines gesamten Strings zurückgegeben. Es handelt sich hierbei ausschließlich um den HTTP-Body.

Falls ein Fehler aufgetreten ist, ist dieser Wert mit einem Leersting gefüllt (<code>$data = ""</code>)
|}

Die Callback-Funktion kann nun die Daten aus der HTTP-Antwort verarbeiten oder bei Fehlern entsprechende Log-Meldungen ausgeben.

==== Beispiel für HttpUtils_NonblockingGet() für Modulprogrammierer ====
Das folgende Beispiel soll eine Hilfestellung für eigene Anwendungen geben

<syntaxhighlight lang="perl">use HttpUtils;
sub X_PerformHttpRequest($)
{
my ($hash, $def) = @_;
my $name = $hash->{NAME};
my $param = {
url => "http://www.foo.de/",
timeout => 5,
hash => $hash, # Muss gesetzt werden, damit die Callback funktion wieder $hash hat
method => "GET", # Lesen von Inhalten
header => "User-Agent: TeleHeater/2.2.3\r\nAccept: application/json", # Den Header gemäß abzufragender Daten ändern
callback => \&X_ParseHttpResponse # Diese Funktion soll das Ergebnis dieser HTTP Anfrage bearbeiten
};

HttpUtils_NonblockingGet($param); # Starten der HTTP Abfrage. Es gibt keinen Return-Code.
}

sub X_ParseHttpResponse($)
{
my ($param, $err, $data) = @_;
my $hash = $param->{hash};
my $name = $hash->{NAME};

if($err ne "") # wenn ein Fehler bei der HTTP Abfrage aufgetreten ist
{
Log3 $name, 3, "error while requesting ".$param->{url}." - $err"; # Eintrag fürs Log
readingsSingleUpdate($hash, "fullResponse", "ERROR", 0); # Readings erzeugen
}

elsif($data ne "") # wenn die Abfrage erfolgreich war ($data enthält die Ergebnisdaten des HTTP Aufrufes)
{
Log3 $name, 3, "url ".$param->{url}." returned: $data"; # Eintrag fürs Log

# An dieser Stelle die Antwort parsen / verarbeiten mit $data

readingsSingleUpdate($hash, "fullResponse", $data, 0); # Readings erzeugen
}

# Damit ist die Abfrage zuende.
# Evtl. einen InternalTimer neu schedulen
}</syntaxhighlight>

=== HttpUtils_Close ===

Für den Abbruch von offenen Verbindungen und noch laufenden NonBockingGet-Aufrufen gibt es die Funktion HttpUtils_Close. Diese kann z.B. beim Löschen eines Devices oder Herunterfahren des Servers aufgerufen werden, um bestehende Verbindungen zu schliessen.

Wenn man den Parameter "keepalive" beim Aufruf von HttpUtils_NonBlockingGet/HttpUtils_BlockingGet gesetzt hat, muss man HttpUtils_Close aufrufen um die Verbindung tatsächlich zu schließen, da diese noch durch den Server offen gehalten werden kann.

'''Aufruf: <code>HttpUtils_Close($param)</code>'''

{| class="wikitable"
|-
! style="width:175px" | Parameter !! style="width:auto" | Bedeutung
|-
| style="vertical-align:top" | '''<code>$param</code>'''

''mandatory''
|| Der Hash, der beim vorherigen Aufruf an HTTPUtils Funktionen (HttpUtils_NonblockingGet oder HttpUtils_BlockingGet) übergeben wurde

|}

== Hilfsfunktionen ==

=== urlEncode ===

:<syntaxhighlight lang="perl">
$encoded = urlEncode($string);
</syntaxhighlight>
Die Funktion urlEncode() wandelt die übergebene Zeichenkette <code>$string</code> in eine URL-kompatible<ref name="rfc3986-2.1">[https://tools.ietf.org/html/rfc3986#section-2.1 RFC 3989] - Abschnitt 2.1 "Percent-Encoding"</ref> Zeichenkette um. Der Rückgabewert <code>$encoded</code> ist eine Zeichenkette welche innerhalb einer URL verwendet werden kann, bspw. als Wert eines GET-Parameters.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$string</code>'''

''mandatory''
|| Die Zeichenkette, welche in eine URL-kompatible Form umgewandelt werden soll.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$encoded </code>''' || Die URL-kompatible Version der übergebenen Zeichenkette. Problematische Zeichen sind in diesem Wert durch ein Prozentzeichen gefolgt von der Hexadezimaldarstellung des Zeichens dargestellt.

Bsp:
* "a: b" => "a%3a%20b"
* "a/b" => "a%2fb"
|}

=== urlDecode ===

:<syntaxhighlight lang="perl">
$string = urlDecode($encoded);
</syntaxhighlight>
Die Funktion urlDecode () normalisiert die übergebene Zeichenkette <code>$encoded</code> und ersetzt dabei sämtliche Hexadezimaldarstellungen<ref name="rfc3986-2.1" /> (eingeleitet mit einem Prozentzeichen) durch die entsprechenden Zeichen. Der Rückgabewert <code>$string</code> ist eine Zeichenkette welche keinerlei Hexadezimaldarstellungen mehr aufweist.

Parameter:
{| class="wikitable"
|-
! Parameter !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$encoded</code>'''

''mandatory''
|| Eine Zeichenkette, welche URL-kombatible Hexadezimaldarstellungen enthält.
|}

Rückgabewerte:
{| class="wikitable"
|-
! Rückgabewert !! Bedeutung
|-
| style="vertical-align:top" | '''<code>$string</code>''' || Die normale Version der übergebenen Zeichenkette. Sämtliche Hexadezimalddarstellungen sind in ihre entsprechenden Zeichen umgewandelt.

Bsp:
* "a%3a%20b" => "a: b"
* "a%2fb" => "a/b"
|}

== Referenzen ==

<references />

[[Kategorie:Development]]

Buienradar

2020-05-19T12:10:43Z

ChristophMorrison: Added external links

See the [https://github.com/fhem/mod-Buienradar/wiki project wiki] and the documentation ([https://github.com/fhem/mod-Buienradar/blob/stable/CommandRef.en.md english], [https://github.com/fhem/mod-Buienradar/blob/stable/CommandRef.de.md german]).

99 myUtils anlegen

2020-02-04T11:42:12Z

ChristophMorrison: Linked 99_Utils from SVN

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>
Name
 
Text 
Examples:
<ul>
<code>Example Code </code> 
</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 ==
=== Globale Ablage von Daten ===
Um Daten zentral zwischenzuspeichern, kann man
* die Funktionen ''[[DevelopmentModuleAPI#setKeyValue|setKeyValue()]]'' bzw. ''getKeyValue()'' nutzen, um die Daten im Dateisystem abzulegen;
* in den globalen Hash ''%data schreiben'', wie in diesem {{Link2Forum|Topic=63737|LinkText=Forumsbeitrag}} erläutert.

=== Vertiefende 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 [https://svn.fhem.de/trac/browser/trunk/fhem/FHEM/99_Utils.pm 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]]

Buienradar

2019-07-22T19:01:54Z

ChristophMorrison: Die Seite wurde neu angelegt: „tbd“

tbd

AutoShuttersControl

2019-07-11T13:50:24Z

ChristophMorrison:

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Steuerung von Rollläden
|ModCategory=Automatisierung
|ModType=d
|ModForumArea=Automatisierung
|ModTechName=73_AutoShuttersControl.pm
|ModOwner=CoolTux ({{Link2FU|13684|Forum}}/[[Benutzer Diskussion:CoolTux|Wiki]])}}

Mit [[AutoShuttersControl]] oder kurz ASC können typische Aufgabenstellungen im Zusammenhang mit Rollläden u.ä. automatisiert werden, wie zum Beispiel das Öffnen bei Sonnenaufgang, Schließen bei Sonnenuntergang oder das Anfahren von Lüftungspositionen beim Öffnen des zugehörigen Fensters.

== Basics ==
{{Hinweis|Das Modul befindet sich derzeit noch in der Entwicklung; der jeweils aktuelle Stand ist diesem {{Link2Forum|Topic=90751|LinkText="Thread im Forum"}} zu entnehmen.}}
Zur Nutzung des Moduls sollten folgende andere FHEM-Devices vorhanden sein:
* Rollläden
* Fensterkontakte und
* Bewohnerstatus auf Basis von Residents/Roomates in englisch. Ersatzweise andere Devices, z.B. Dummys, welche als ''state'' ''home'', ''asleep'', ''gotosleep'' und ''awoken'' setzen sowie ein Reading ''lastState''.
* Optional:
** Ein Helligkeitssensor (Steuerung nach Helligkeit und Beschattung)
** Ein Device zur Bestimmung des Sonnenstands (nur für Beschattung). Unterstützt werden derzeit [[Modul Astro|Astro]] und [[Twilight]]<ref>Dabei müssen ggf. in [[Global|global]] auch Angaben zu ''longitude'' und ''latitude'' vorhanden sein</ref>.
** Wenn Feiertage berücksichtigt werden sollen: Ein oder mehrere {{Link2CmdRef|Anker=holiday2we|Lang=en|Label=holiday2we}}-Angaben in [[Global|global]] samt entsprechender [[Wochenende, Feiertage und Schulferien#Feiertage mittels holiday-Datei|holiday]]-Dateien<ref>Es kann auch z.B. ein Dummy-Device verwendet werden, dieses sollte dann aber neben dem eigentlichen Feiertags-''state'' auch in einem Reading ''tomorrow'' Angaben zu anstehenden Feiertagen enthalten.</ref> <ref>Bitte verfahren Sie entsprechend, wenn Urlaubs- oder Ferientage wie Feiertage behandelt werden sollen.</ref>.

Die Einrichtung des Moduls bzw. dessen Funktionalität erfolgt in mehreren Schritten:
* Definition des ASC-Devices
* Einstellung zentraler Vorgaben am ASC-Device
* Markieren der zukünftig zu steuernden Rollladen-Devices
* Einbinden der Rollladen-Devices in das ASC-Device
* Einstellen der individuellen Vorgaben je Rollladen (am Rollladen-Device)
Dabei geht man am einfachsten schrittweise vor und erweitert die Funktionalität nach und nach um die gewünschten Funktionen. Dann benötigt man jeweils nur einen kleinen Teil der vielen per Attribut einstellbaren Optionen, und kann die Auswirkungen der jeweiligen Änderung besser nachvollziehen.

== Einrichtung ==
{{Hinweis|ASC kann auch verwendet werden, um lediglich Teilaufgaben der Rollladensteuerung zu erfüllen, also z.B. nur das morgendliche Öffnen der Rollläden. Allerdings geht dabei ein erheblicher Teil des Komforts verloren, der dadurch entsteht, dass die Steuerung innerhalb der vollintegrierten Lösung jeweils nachvollzieht, aus welchem Grund eine Fahrt erfolgt war und dies ggf. bei der nächsten Aktion berücksichtigt.}}

=== Vorbereitung ===
Zunächst sollten die in den [[#Basics|Basics]] beschriebenen Geräte vorhanden und funktionsfähig sein.

=== Define des ASC-Devices ===
Es genügt ein einfaches define ohne weitere Parameter.
<code>define <name> AutoShuttersControl</code>
Dies bewirkt neben der Anlage des Devices selbst auch, dass als weiteres globales Attribut ''ASC'' verfügbar wird.

=== Einstellung zentraler Vorgaben ===
Es stehen am ASC-Device einige Attribute zur Verfügung, über die sich das Verhalten des ASC-Devices insgesamt steuern lässt, z.B. zur Vermeidung von morgendlichen oder abendlichen Fahrten sowie bei Gefahr von Schäden an den Rollläden durch Frost oder zur Reaktion auf Fensterkontakte. Details sind der Commandref zu entnehmen.
Diese Attribute können auch nachträglich noch geändert werden.

=== Markieren zu steuernder Rollladen-Devices ===
Um einen oder mehrere Rollläden durch das ASC-Device zu steuern, wird für jeden Rollladen jeweils das neue globale Attribut ''ASC'' gesetzt. Der Wert ist mit 1 oder 2 festzulegen, wobei '''1''' bedeutet, dass
* die Offen-Position kleiner ist als die Geschlossen-Position, also typischerweise 0 ''offen'' bedeutet und 100 für ''geschlossen'' steht
* eine bestimmte Position mit '''position''' angefahren wird, also z.B. <code>set <name> position 70</code>.
Dies ist z.B. die passende Wahl für ROLLO-Devices

Die '''2''' steht für ein umgekehrtes Verhalten und den Befehlsteil ''pct'', also ''offen'' für <code>set <name> pct 100</code>. Typischer Vertreter dieses Typs sind HomeMatic (CUL_HM-) Geräte oder die Shelly2-Aktoren.

=== Einbinden in das ASC-Device ===
Nachdem man das obige Attribut bei einem oder mehreren Rollladen-Devices gesetzt hat, kann mit
<code>set <name> scanForShutters</code> ein Suchlauf gestartet werden, mit dem dann diese Rollläden durch das Modul gefunden und in die Steuerungslogik eingebunden werden.

=== Einstellen der individuellen Vorgaben ===
Nach der Einbindung sind an den Rollladen-Devices weitere Attribute verfügbar, mit denen die für den jeweiligen Rollladen geltenden Einstellungen vorgenommen werden können.
Die Beschreibung der Attribute ist in der commandref enthalten.

== Readings ==

===Readings im ASC-Device selbst ===

{|class="wikitable"
|-
! Name !! Datentyp/ Wertebereich !! Bedeutung
|-
|..._nextAstroTimeEvent || ||Uhrzeit des nächsten Astro-Events, Sonnenauf- oder Sonnenuntergang oder feste Zeit pro Rollonamen
|-
|..._lastPosValue || ||zuletzt abgesetzter Fahrbefehl pro Rollonamen
|-
|..._lastDelayPosValue || ||zuletzt abgesetzter Fahrbefehl, welcher beim nächsten zulässigen Event ausgeführt wird
|-
|partyMode ||on, off || aktiviert den globalen Partymodus. Alle Rollläden, welche das Attribut ''AutoShuttersControl_Partymode'' bei sich auf ''on'' gestellt haben, werden nicht mehr gesteuert. Der letzte Schaltbefehl, welcher durch ein Fensterevent oder Bewohnerstatus an die Rollläden gesendet wurde, wird erst beim off-setzen (set <ASC-Device> partyMode off) ausgeführt
|-
|lockOut || on, off ||für das Aktivieren des Aussperrschutzes gemäß des entsprechenden Attributs ''AutoShuttersControl_lock-out'' im jeweiligen Rolladen (siehe Beschreibung bei den Attributen für die Rolladendevices)
|-
|room_... || ||Auflistung aller Rollläden, welche in den jeweiligen Räumen gefunden wurden, Bsp.: room_Schlafzimmer,Terrasse
|-
|state || ||Status des <ASC-Device> active, enabled, disabled
|-
|sunriseTimeWeHoliday|| on,off ||legt fest, ob das Rolladendevice das Attribut ''AutoShuttersControl_Time_Up_WE_Holiday'' beachtet oder nicht
|-
|userAttrList || rolled out ||Status der UserAttribute, welche an die Rollläden gesendet werden
|}

=== Readings in den Rolllädendevices ===

{|class="wikitable"
|-
! Name !! Bedeutung
|-
|ASC_Time_DriveUp ||Sonnenaufgangszeit für das Rollo
|-
|ASC_Time_DriveDown ||Sonnenuntergangszeit für das Rollo
|-
|ASC_ShuttersLastDrive ||Grund des letzten Fahrens vom Rolladen
|}

==set- und get-Befehle für das ASC-Device==

=== set-Anweisungen ===
{|class="wikitable"
|-
! Name !! Datentyp/ Wertebereich !! Beschreibung
|-
|partyMode ||on, off ||aktiviert den globalen Partymodus. Siehe Reading ''partyMode''
|-
|lockOut ||on, off ||aktiviert den globalen Aussperrschutz. Siehe Reading ''lockOut''
|-
|renewSetSunriseSunsetTimer || || erneuert bei allen Rollläden die Zeiten für Sunset und Sunrise und setzt die internen Timer neu.
|-
|scanForShutters || ||sucht alle FHEM Devices mit dem Attribut ''AutoShuttersControl'' ''1'' oder ''2''
|-
|sunriseTimeWeHoliday || on,off ||aktiviert/deaktiviert die Beachtung des Attributes ''AutoShuttersControl_Time_Up_WE_Holiday'' für Rollladen-Devices
|-
|createNewNotifyDev || ||Legt die interne Struktur für NOTIFYDEV neu an
|-
|selfDefence ||on, off||aktiviert/deaktiviert den Selbstschutz: wenn das Residents-Device ''absent'' meldet, ''selfDefence'' aktiv ist und ein Fenster im Haus noch offen steht, wird an diesem Fenster das Rollo runtergefahren
|-
|wiggle ||||bewegt einen Rollladen oder alle Rollläden (für Abschreckungszwecke bei der Alarmierung) um ''ASC_WiggleValue''-%, und nach 1 Minute wieder zurück zur Ursprungsposition
|-
|||||
|}

=== get-Anweisungen ===

{|class="wikitable"
|-
! Name !! Beschreibung
|-
| showShuttersInformations ||zeigt eine Übersicht der Automatik-Fahrzeiten
|-
| showNotifyDevsInformations ||zeigt eine Übersicht der abgelegten NOTIFYDEV Struktur. Dient zur Kontrolle
|}
== Attribute ==
{{Hinweis|Die Attributnamen haben sich teilweise geändert, nachfolgend ist noch ein Stand vor Modulversion 0.6.5.x wiedergegeben. Die aktuellen Benennungen sind der Commandref zu entnehmen.}}
{{Hinweis|In der commandref findet sich häufig die Schreibweise <code>ASC_BrightnessSensor Sensorname[:brightness [400:800]]</code>. Dabei sind die Angaben in den eckigen Klammern optional. Dies müssen also nicht angegeben werden, stattdessen verwendet das Modul dann Standardwerte (siehe cref), die in der cref zu findenden Angaben entsprechen dabei den defaults. Werden Werte angegeben, sind die eckigen Klammern '''wegzulassen'''! Beispiel: <code>ASC_BrightnessSensor hm_motion_1 70:100</code> würde das brightness-Reading des Sensors hm_motion_1 verwenden und einen morgendlichen Schwellenwert von 70 bzw. 100 für abends.}}
===Attribute direkt am ASC-Device ===

{|class="wikitable"
|-
! Name !! Datentyp/ Wertebereich !! Default-Wert !! Beschreibung
|-
|ASC_antifreezeTemp || || ||Temperatur, ab welcher der Frostschutz greift und das Rollo nicht mehr fährt. Der letzte Fahrbefehl wird gespeichert
|-
|ASC_autoAstroModeEvening ||aktuell REAL, CIVIL, NAUTIC, ASTRONOMIC, HORIZON || || (in genau dieser Schreibweise)
|-
|ASC_autoAstroModeEveningHorizon || || || Höhe über Horizont, wenn beim Attribut ''AutoShuttersControl_autoAstroModeEvening'' ''HORIZON'' ausgewählt
|-
|ASC_autoAstroModeMorning ||aktuell REAL, CIVIL, NAUTIC, ASTRONOMIC, HORIZON || ||(in genau dieser Schreibweise)
|-
|ASC_autoAstroModeMorningHorizon || || ||Höhe über Horizont, wenn beim Attribut ''AutoShuttersControl_autoAstroModeMorning'' ''HORIZON'' ausgewählt
|-
|ASC_autoShuttersControlComfort ||on, off || ||aktiviert die Komfortfunktion. Bedeutet, dass ein Rollladen mit einem threestate (Drehgriff-) Sensor am Fenster beim Öffnen in die "Komfortposition" fährt. Diese wird beim Rollladendevice über das Attribut ''AutoShuttersControl_Pos_after_ComfortOpen'' eingestellt.
|-
|ASC_autoShuttersControlEvening ||on, off || ||ob Abends die Rollläden automatisch zeitgesteuert werden sollen
|-
|ASC_autoShuttersControlMorning ||on, off || ||ob Morgens die Rollläden automatisch zeitgesteuert werden sollen
|-
|ASC_temperatureReading || || ||Reading für die Außentemperatur
|-
|ASC_temperatureSensor || || ||Device für die Außentemperatur
|-
|ASC_timeUpHolidayDevice || || ||Device zur Urlaubserkennung oder Sonstiges / muss ''0'' oder ''1'' im Reading ''state'' beinhalten.
|-
|ASC_residentsDevice|| || ||Devicenamen des Residents-Device der obersten Ebene
|-
|ASC_residentsDeviceReading|| || ||Status Reading des Residents-Device der obersten Ebene
|-
|ASC_brightnessMinVal|| || ||minimaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen
|-
|ASC_brightnessMaxVal || || ||maximaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen
|-
|ASC_rainSensorDevice || || ||Device, welches bei Regen getriggert wird
|-
|ASC_rainSensorReading || || ||das ensprechende Reading zum Regendevice
|-
|ASC_rainSensorShuttersClosedPos || || ||Position in pct, welche der Rollladen bei Regen anfahren soll
|-
|ASC_shuttersDriveOffset || || ||maximale zufällige Verzögerung in Sekunden bei der Berechnung der Fahrzeiten, ''0'' bedeutet keine Verzögerung
|-
|ASC_twilightDevice || || ||Device, welches Informationen zum Sonnenstand liefert, wird unter anderem für die Beschattung verwendet.
|-
|ASC_expert || || ||bei ''1'' werden erweiterte Informationen bezüglich des NotifyDevs unter ''set'' und ''get'' angezeigt
|-
| || || ||
|-
| || || ||
|}

===Attribute in den Rolllädendevices===

{|class="wikitable"
|-
! Name !! Datentyp/ Wertebereich !! Default-Wert !! Beschreibung
|-
|ASC || 0, 1, 2|| ||0 = "kein Anlegen der Attribute beim ersten Scan bzw. keine Beachtung eines Fahrbefehles",1 = "Inverse oder Rollo - Bsp.: Rollo Oben 0, Rollo Unten 100 und der Befehl zum prozentualen Fahren ist position",2 = "Homematic Style - Bsp.: Rollo Oben 100, Rollo Unten 0 und der Befehl zum prozentualen Fahren ist pct
|-
|ASC_Antifreeze || soft, am, pm, hard, off|| ||Frostschutz, wenn ''soft'' fährt der Rollladen in die ''ASC_Antifreeze_Pos'', bei ''hard/am/pm'' wird gar nicht oder innerhalb der entsprechenden Tageszeit nicht gefahren
|-
|ASC_Antifreeze_Pos || || ||Position, die angefahren werden soll, wenn der Fahrbefehl komplett schließen lautet, aber der Frostschutz aktiv ist
|-
|ASC_AutoAstroModeEvening ||REAL, CIVIL, NAUTIC, ASTRONOMIC, HORIZON || ||aktuell REAL,CIVIL,NAUTIC,ASTRONOMIC
|-
|ASC_AutoAstroModeEveningHorizon || || ||Höhe über Horizont, wenn beim Attribut ''ASC_autoAstroModeEvening'' ''HORIZON'' ausgewählt ist
|-
|ASC_AutoAstroModeMorning ||REAL, CIVIL, NAUTIC, ASTRONOMIC, HORIZON || ||aktuell REAL,CIVIL,NAUTIC,ASTRONOMIC
|-
|ASC_AutoAstroModeMorningHorizon || || ||Höhe über Horizont, wenn beim Attribut ''ASC_autoAstroModeMorning'' ''HORIZON'' ausgewählt ist
|-
|ASC_Closed_Pos || || ||in 10er Schritten von 0 bis 100,default Vorgabe ist abhängig vom Attribut ''ASC''
|-
|ASC_Down || astro, time, brightness || ||bei ''astro'' wird Sonnenuntergang berechnet, bei ''time'' wird der Wert aus ''ASC_Time_Down_Early'' als Fahrzeit verwendet und bei ''brightness'' muss ''ASC_Time_Down_Early'' und ''ASC_Time_Down_Late'' korrekt gesetzt werden. Der Timer läuft dann nach ''ASC_Time_Down_Late''-Zeit,es wird aber in der Zeit zwischen ''ASC_Time_Down_Early'' und ''ASC_Time_Down_Late'' geschaut, ob die als Attribut im Moduldevice hinterlegte ''ASC_brightnessMinVal'' erreicht wurde. Wenn ja, wird der Rolladen runter gefahren
|-
|ASC_Mode_Down ||always, home, absent, off || ||wann darf die Automatik herunterfahren. immer, niemals oder bei Abwesenheit des Roommate (ist kein Roommate und ''absent'' eingestellt, wird gar nicht gesteuert)
|-
|ASC_Mode_Up ||always, home, absent, off || ||wann darf die Automatik hochfahren. immer, niemals oder bei Abwesenheit des Roommate (ist kein Roommate und ''absent'' eingestellt, wird gar nicht gesteuert)
|-
|ASC_Drive_Offset || || ||maximale zufällige Verzögerung in Sekunden bei der Berechnung der Fahrzeiten, ''0'' bedeutet sofort, ''-1'' bedeutet, dass das gleichwertige Attribut aus dem ASC-Device ausgewertet werden soll
|-
|ASC_Open_Pos || || ||in 10er-Schritten von 0 bis 100, default Vorgabe ist abhängig vom Attribut ''ASC''
|-
|ASC_Partymode || on, off || ||schaltet den Partymodus an oder aus. Wird dann am ASC Device ''set <ASC-DEVICE> partyMode on'' geschaltet, werden alle Fahrbefehle an den Rollläden, welche das Attribut auf ''on'' haben, zwischengespeichert und erst später ausgeführt
|-
|ASC_Pos_Reading || || ||Name des Readings, welches die Position des Rollladen in Prozent angibt. Wird bei unbekannten Device-Typen auch als ''set'' Befehl zum Fahren verwendet
|-
|ASC_Pos_after_ComfortOpen || || ||in 10er-Schritten von 0 bis 100, default Vorgabe ist abhängig vom Attribut ''ASC''
|-
|ASC_Roommate_Reading || || ||Reading des Roommate-Device, welches den Status wieder gibt
|-
|ASC_Roommate_Device || || ||mit Komma getrennte Namen des/der Roommate-Device/s welche den/die Bewohner des Rollladen-Raumes wiedergibt. Macht nur Sinn in Schlaf- oder Kinderzimmern
|-
|ASC_Time_Down_Early || || ||Sunset früheste Zeit zum Runterfahren
|-
|ASC_Time_Down_Late || || ||Sunset späteste Zeit zum Runterfahren
|-
|ASC_Time_Up_Early || || ||Sunrise früheste Zeit zum Hochfahren
|-
|ASC_Time_Up_Late || || ||Sunrise späteste Zeit zum Hochfahren
|-
|ASC_Time_Up_WE_Holiday || || ||Sunrise früheste Zeit zum Hochfahren am Wochenende und/oder Urlaub (holiday2we wird beachtet).
|-
|ASC_Up || astro, time, brightness || ||bei ''astro'' wird Sonnenaufgang berechnet, bei ''time'' wird der Wert aus ''ASC_Time_Up_Early'' als Fahrzeit verwendet und bei ''brightness'' müssen ''ASC_Time_Up_Early'' und ''ASC_Time_Up_Late'' korrekt gesetzt werden. Der Timer läuft dann nach ''ASC_Time_Up_Late''-Zeit, es wird aber in der Zeit zwischen ''ASC_Time_Up_Early'' und ''ASC_Time_Up_Late'' geschaut, ob die als Attribut im Moduldevice hinterlegte ''ASC_brightnessMinVal'' erreicht wurde. Wenn ja, wird der Rolladen runter gefahren
|-
|ASC_Ventilate_Pos || || ||in 10er-Schritten von 0 bis 100, default Vorgabe ist abhängig vom Attribut ''ASC''
|-
|ASC_Ventilate_Window_Open || || ||auf lüften, wenn das Fenster gekippt/geöffnet wird und aktuelle Position unterhalb der Lüften-Position ist
|-
|ASC_WindowRec || || ||Name des Fensterkontakts, an welchen Fenster der Rollladen angebracht ist. Sein Reading ''state'' muss die Werte ''open'', ''closed'' oder ''tilted'' enthalten.
|-
|ASC_WindowRec_subType || || ||Typ des verwendeten Fensterkontakts: ''twostate'' (optisch oder magnetisch) oder ''threestate'' (Drehgriffkontakt)
|-
|ASC_LockOut || soft, hard || ||stellt entsprechend den Aussperrschutz ein. Bei global aktiven Aussperrschutz (''set ASC-Device lockOut soft'') und einem Fensterkontakt ''open'' bleibt dann der Rolladen oben. Dies gilt nur bei Steuerbefehle über das ASC-Modul. Stellt man global auf ''hard'', wird bei entsprechender Möglichkeit versucht, den Rollladen hardwareseitig zu blockieren. Dann ist auch ein Fahren über die Taster nicht mehr möglich.
|-
|ASC_LockOutCmd || inhibit, blocked || ||set Befehl für das Rolladen-Device zum Sperren per Hardware. Der Befehl wird verwendet, wenn ''ASC_LockOut'' auf ''hard'' gesetzt ist
|-
|ASC_Self_Defense_Exclude || on, off || ||bei ''on'' wird dieser Rolladen bei aktiven ''selfDefence'' und offenen Fenster nicht runter gefahren, wenn Residents absent ist
|-
|ASC_Shading_Brightness_Sensor || || ||Sensor-Device, welches für die Lichtwerte verwendet wird. ACHTUNG! Findet auch Verwendung bei ASC_Down - brightness
|-
|ASC_BrightnessMinVal || || ||minimaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen / wird der Wert von ''-1'' nicht geändert, so wird automatisch der Wert aus dem Moduldevice genommen
|-
|ASC_BrightnessMaxVal || || ||maximaler Lichtwert, bei dem Schaltbedingungen noch geprüft werden sollen / wird der Wert von ''-1'' nicht geändert, so wird automatisch der Wert aus dem Moduldevice genommen
|-
|ASC_ShuttersPlace || window, terrace || ||wenn dieses Attribut auf ''terrace'' gesetzt ist und das Residents-Device in den Status ''gone'' geht und ''selfDefence'' aktiv ist, wird das Rollo geschlossen
|-
|ASC_WiggleValue || || ||Wert, um welchen sich die Position des Rollladens bei ''Wiggle'' ändern soll
|-
|ASC_BlockingTime_afterManual || || ||Wartezeit in Sekunden, die die Automatik nach einer manuellen Fahrt aussetzen soll
|-
|ASC_BlockingTime_beforNightClose || || ||Vorgabezeit in Sekunden, innerhalb derer vor dem nächtlichen Schließen keine Öffnen-Fahrt mehr ausgeführt werden soll
|-
|ASC_BlockingTime_beforDayOpen || || ||Vorgabezeit in Sekunden, innerhalb derer vor dem morgendlichen Öffnen keine Schließen-Fahrt mehr ausgeführt werden soll
|-
|ASC_Shading_Direction || || ||Position in Grad, auf der das Fenster liegt - genau Osten wäre 90, Süden 180 und Westen 270
|-
|ASC_Shading_Pos || || ||Position des Rollladens für die Beschattung
|-
|ASC_Shading_Angle_Left || || ||Vorlaufwinkel im Bezug zum Fenster, ab wann abgeschattet wird. Beispiel: Fenster 180° - 85° ==> ab Sonnenpos. 95° wird abgeschattet
|-
|ASC_Shading_Angle_Right || || ||Nachlaufwinkel im Bezug zum Fenster, bis wann abgeschattet wird. Beispiel: Fenster 180° + 85° ==> bis Sonnenpos. 265° wird abgeschattet
|-
|ASC_Shading_Mode || || ||absent,always,off,home / Vorgabe, wann Beschattungsaktionen durchzuführen sind
|-
|ASC_Shading_StateChange_Sunny || || ||Brightness Wert ab welchen Beschattung statt finden soll, immer in Abhängikkeit der anderen einbezogenden Sensorwerte
|-
|ASC_Shading_StateChange_Cloudy || || ||Brightness Wert ab welchen die Beschattung aufgehoben werden soll, immer in Abhängikkeit der anderen einbezogenden Sensorwerte
|-
|ASC_Shading_Min_Elevation || || ||ab welcher Höhe des Sonnenstandes soll beschattet werden, immer in Abhängikkeit der anderen einbezogenden Sensorwerte
|-
|ASC_Shading_Min_OutsideTemperature || || ||ab welcher Temperatur soll Beschattet werden, immer in Abhängikkeit der anderen einbezogenden Sensorwerte
|-
|ASC_Shading_WaitingPeriod || || ||wie viele Sekunden soll gewartet werden bevor eine weitere Auswertung der Sensordaten für die Beschattung statt finden soll
|-
|ASC_PrivacyDownTime_beforNightClose || || ||wie viele Sekunden vor dem abendlichen schlie&zlig;en soll der Rollladen in die Sichtschutzposition fahren, -1 bedeutet das diese Funktion unbeachtet bleiben soll
|-
|ASC_PrivacyDown_Pos || || ||Position den Rollladens für den Sichtschutz
|-
| || || ||
| || || ||
|-
| || || ||
|-
| || || ||
|-
| || || ||
|}

== Hilfsmittel ==
{{Hinweis|Die Device-Namen sind auf die eigene Installation anzupassen.}}

=== Interne Übersicht ===
[[Bild:ASC Overview.JPG|thumb|right|weblink - Beispiel]]
<pre style="width:65%;word-break: break-all;word-wrap: break-word;">
define ASC_Jalousie_Info weblink htmlCode {AutoShuttersControl::GetShuttersInformation($defs{'JalousieControl'})}
</pre>

{{Hinweis|Codezeilen sind im [[Import von Code Snippets|RAW]]-Format.}}

=== readingsGroup für Level ===

{{Randnotiz|RNTyp=g|RNText= Stand 2019-05-03
* Erfolgreich getestet mit Homematic Devices, Beta-User
* Die Farbgebung entspricht dem Standard, wenn unter dem Style f18 der Farbpreset ''light'' gewählt wird.
}}

<pre style="width:65%;word-wrap: break-word;">defmod rg_ASC_Rolllaeden_Level readingsGroup <Gerät>,<Stand>,<Schliessen bis>,<Öffnen auf>,<Beschattung>,<Komfort>,<Lüften>,<Privacy> (Rollladen_.*|Jalousie_.*)..:level,!?ASC_Closed_Pos,!?ASC_Open_Pos,!?ASC_Shading_Pos,!?ASC_ComfortOpen_Pos,!?ASC_Ventilate_Pos,!?ASC_PrivacyDown_Pos
attr rg_ASC_Rolllaeden_Level commands {level => 'pct:selectnumbers,0,5,100,0,lin',\
ASC_Closed_Pos => 'ASC_Closed_Pos:selectnumbers,0,5,100,0,lin',\
ASC_Open_Pos => 'ASC_Open_Pos:selectnumbers,0,5,100,0,lin',\
ASC_Shading_Pos => 'ASC_Shading_Pos:selectnumbers,0,5,100,0,lin',\
ASC_Ventilate_Pos => 'ASC_Ventilate_Pos:selectnumbers,0,5,100,0,lin',\
ASC_ComfortOpen_Pos => 'ASC_ComfortOpen_Pos:selectnumbers,0,5,100,0,lin',\
ASC_PrivacyDown_Pos => 'ASC_PrivacyDown_Pos:selectnumbers,0,5,100,0,lin'}
</pre>

=== readingsGroup für Zeiten ===
[[Bild:ReadingsGroup ASC times.png|thumb|right|ReadingsGroup - Zeitenbeispiel]]
<pre style="width:65%;word-wrap: break-word;">defmod rg_ASC_Rolllaeden_Times readingsGroup <Gerät>,<Position>,<Time_Up_Early>,<Time_Up_Late>,<Time_Up_WE/Hol>,<Time_Down_Early>,<Time_Down_Late>,<Mode_Down>,<Mode_Up> \
(.*Rollo.*|.*Rollladen|Jalousie_.*):level,?ASC_Time_Up_Early,?ASC_Time_Up_Late,?ASC_Time_Up_WE_Holiday,?ASC_Time_Down_Early,?ASC_Time_Down_Late,?ASC_Mode_Down,?ASC_Mode_Up
attr rg_ASC_Rolllaeden_Times commands {level => 'pct:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,100', \
ASC_Time_Down_Early => 'ASC_Time_Down_Early:15:00,15:15,15:30,15:45,16:00,16:15,16:30,16:45,17:00,17:15,17:30,17:45,18:00,18:15,18:30,18:45,19:00,19:15,19:30,19:45,20:00,20:15,20:30,20:45,21:00,21:15,21:30,21:45,22:00', \
ASC_Time_Down_Late => 'ASC_Time_Down_Late:19:00,19:15,19:30,19:45,20:00,20:15,20:30,20:45,21:00,21:15,21:30,21:45,22:00,22:15,22:30,22:45,23:00,23:15,23:30', \
ASC_Time_Up_WE_Holiday => 'ASC_Time_Up_WE_Holiday:06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00',\
ASC_Time_Up_Early => 'ASC_Time_Up_Early:05:00,05:05,05:30,05:55,06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00', \
ASC_Time_Up_Late => 'ASC_Time_Up_Late:06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00', \
ASC_Mode_Down => 'ASC_Mode_Down:always,absent,off', \
ASC_Mode_Up => 'ASC_Mode_Up:always,absent,off' }
attr rg_ASC_Rolllaeden_Times room Rollladen</pre>

[[Bild:ASC RG Zeiten HM ZWave Siro.png|thumb|right|ReadingsGroup - CUL_HM+ZWave+Siro mit widgets]]Neue Version mit time-Widgets und pct/dim/position-widget (5-er Schritte), passend für CUL_HM, ZWave und Siro-Geräte:
<pre style="width:65%;word-wrap: break-word;">defmod rg_ASC_Rolllaeden_Times readingsGroup <Gerät>,<Stand>,<Time_Up_Early >,<Time_Up_WE >,<Time_Up_Late >,<Time_Down_Early>,<Time_Down_Late>,<Mode_Down>,<Mode_Up> (Rollo_.*|Jalousie_.*)..:(level|dim|position),!?ASC_Time_Up_Early,!?ASC_Time_Up_WE_Holiday,!?ASC_Time_Up_Late,!?ASC_Time_Down_Early,!?ASC_Time_Down_Late,!?ASC_Mode_Down,!?ASC_Mode_Up
attr rg_ASC_Rolllaeden_Times commands {level => 'pct:selectnumbers,0,5,100,0,lin', \
dim => 'dim:selectnumbers,0,5,99,0,lin',\
position => 'pct:selectnumbers,0,5,99,0,lin',\
ASC_Mode_Down => 'ASC_Mode_Down:always,absent,off',\
ASC_Mode_Up => 'ASC_Mode_Up:always,absent,off',\
ASC_Time_Down_Early => 'ASC_Time_Down_Early:time', \
ASC_Time_Down_Late => 'ASC_Time_Down_Late:time',\
ASC_Time_Up_Early => 'ASC_Time_Up_Early:time', \
ASC_Time_Up_Late =>'ASC_Time_Up_Late:time',\
ASC_Time_Up_WE_Holiday =>'ASC_Time_Up_WE_Holiday:time'}
attr rg_ASC_Rolllaeden_Times room Rollladen
</pre>

=== readingsGroup für die Beschattung ===
[[Bild:ReadingsGroup ASC shading.png|thumb|right|ReadingsGroup - Beschattungsbeispiel]]
<pre style="width:65%;word-wrap: break-word;">
defmod rg_ASC_Rolllaeden_Shading readingsGroup <Gerät>,<Modus>,<Position>,<Richtung>,<°links>,<°rechts>,<Elevation>,<Sunny>,<Cloudy>,<Min Temp> (Rollo|Jalousie)_.*..:!?ASC_Shading_Mode,!?ASC_Shading_Pos,!?ASC_Shading_Direction,!?ASC_Shading_Angle_Left,!?ASC_Shading_Angle_Right,!?ASC_Shading_MinMax_Elevation,!?ASC_Shading_StateChange_Sunny,!?ASC_Shading_StateChange_Cloudy,!?ASC_Shading_Min_OutsideTemperature

attr rg_ASC_Rolllaeden_Shading alias Rollläden: Beschattung
attr rg_ASC_Rolllaeden_Shading commands {ASC_Shading_Pos => 'ASC_Shading_Pos:knob,min:0,max:100,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:5,lineCap:round',\
ASC_Shading_Mode => 'ASC_Shading_Mode:always,home,absent,off',\
ASC_Shading_Direction => 'ASC_Shading_Direction:knob,min:0,max:360,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:1,cursor:true,lineCap:round',\
ASC_Shading_Angle_Left => 'ASC_Shading_Angle_Left:knob,min:0,max:85,angleArc:85,rotation:anticlockwise,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:5,lineCap:round,angleOffset:270',\
ASC_Shading_Angle_Right => 'ASC_Shading_Angle_Right:knob,min:0,max:85,angleArc:85,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:5,lineCap:round,',\
ASC_Shading_MinMax_Elevation => 'ASC_Shading_MinMax_Elevation:knob,min:0,max:35,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:1,lineCap:round,angleArc:120,angleOffset:270',\
ASC_Shading_StateChange_Sunny => 'ASC_Shading_StateChange_Sunny:knob,min:100,max:1200,angleArc:85,rotation:anticlockwise,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:20,lineCap:round,angleOffset:270',\
ASC_Shading_StateChange_Cloudy => 'ASC_Shading_StateChange_Cloudy:knob,min:100,max:1200,angleArc:85,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:20,lineCap:round,',\
ASC_Shading_Min_OutsideTemperature => 'ASC_Shading_Min_OutsideTemperature:knob,min:5,max:30,width:50,height:50,fgColor:#FF9900,bgColor:#CCCCCC,step:0.5,lineCap:round,angleArc:120,angleOffset:270'}
attr rg_ASC_Rolllaeden_Shading room Rollladen</pre>
 
Anderes {{Link2Forum|Topic=99980|Message=946357|LinkText=Foren-Beispiel}} für eine RG zu Beschattung (für V. 0.6.x):
[[Bild:ReadingsGroup ASC shading2.png|thumb|right|ReadingsGroup - Beschattungsbeispiel]]
<pre style="width:65%;word-wrap: break-word;">
defmod rg_ASC_Shading readingsGroup <Gerät>,<Grad>,<Position>,<Mode>,<Links>,<Rechts>,<Wait>,<ShadeIn>,<ShadeOut>,<Elevation>,<Temperature>,<Device>\
(Rollo_.*|Jalousie.*):!?ASC_Shading_Direction,!?ASC_Shading_Pos,!?ASC_Shading_Mode,!?ASC_Shading_Angle_Left,!?ASC_Shading_Angle_Right,!?ASC_Shading_WaitingPeriod,!?ASC_Shading_StateChange_Sunny,!?ASC_Shading_StateChange_Cloudy,!?ASC_Shading_MinMax_Elevation,!?ASC_Shading_Min_OutsideTemperature,!?ASC_BrightnessSensor\

attr rg_ASC_Shading commands {ASC_Shading_Direction => 'ASC_Shading_Direction:129,255,309',\
ASC_Shading_Pos => 'ASC_Shading_Pos:selectnumbers,0,5,100,0,lin',\
ASC_Shading_Mode => 'ASC_Shading_Mode:absent,always,off,home',\
ASC_Shading_Angle_Left => 'ASC_Shading_Angle_Left:selectnumbers,0,5,100,0,lin',\
ASC_Shading_Angle_Right => 'ASC_Shading_Angle_Right:selectnumbers,0,5,100,0,lin',\
ASC_Shading_WaitingPeriod => 'ASC_Shading_WaitingPeriod:selectnumbers,0,60,1200,0,lin',\
ASC_Shading_StateChange_Sunny => 'ASC_Shading_StateChange_Sunny:selectnumbers,0,20,1000,0,lin',\
ASC_Shading_StateChange_Cloudy => 'ASC_Shading_StateChange_Cloudy:selectnumbers,0,20,1000,0,lin',\
ASC_Shading_MinMax_Elevation =>\
'ASC_Shading_Min_Elevation:selectnumbers,0,1,40,0,lin' ,\
ASC_Shading_Min_OutsideTemperature =>\
'ASC_Shading_Min_OutsideTemperature:selectnumbers,0,1,30,0,lin'}
attr rg_ASC_Shading room Rollladen</pre>

=== readingsGroup für FIBARO Roller Shutter FGR-222 Devices ===
{{Randnotiz|RNTyp=g|RNText=Getestet von majestro84, Stand 2019-01-28.
* https://forum.fhem.de/index.php/topic,92628.msg897099.html#msg897099
* Die Farbgebung entspricht dem Standard, wenn unter dem Style f18 der Farbpreset ''dark'' gewählt wird}}

[[Bild:ASC Jalousien Times.JPG|thumb|right|Beispiel]]
<pre style="width:65%;word-break: break-all;word-wrap: break-word;">define ASC_Jalousien_Times readingsGroup <Gerät>,<Stand>,<Time_Up_Early>,<Time_Up_WE>,<Time_Up_Late>,<Time_Down_Early>,<Time_Down_Late>,<Mode_Down>,<Mode_Up>,<PartyMode>,<LockOut> (.*_Jalousie.*):position,?ASC_Time_Up_Early,?ASC_Time_Up_WE_Holiday,?ASC_Time_Up_Late,?ASC_Time_Down_Early,?ASC_Time_Down_Late,?ASC_Mode_Down,?ASC_Mode_Up,?ASC_Partymode,?ASC_LockOut

attr ASC_Jalousien_Times commands {position => 'dim:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99',
ASC_Mode_Down => 'ASC_Mode_Down:always,absent,off',
ASC_Mode_Up => 'ASC_Mode_Up:always,absent,off',
ASC_Partymode => 'ASC_Partymode:on,off',
ASC_LockOut => 'ASC_LockOut:soft,hard,off',
ASC_Time_Down_Early => 'ASC_Time_Down_Early:15:00,15:15,15:30,15:45,16:00,16:15,16:30,16:45,17:00,17:15,17:30,17:45,18:00,18:15,18:30,18:45,19:00,19:15,19:30,19:45,20:00,20:15,20:30,20:45,21:00,21:15,21:30,21:45,22:00',
ASC_Time_Down_Late => 'ASC_Time_Down_Late:20:15,20:30,20:45,21:00,21:15,21:30,21:45,22:00,22:15,22:30,22:45,23:00,23:15,23:30',
ASC_Time_Up_Early => 'ASC_Time_Up_Early:05:00,05:05,05:30,05:45,06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00',
ASC_Time_Up_Late =>'ASC_Time_Up_Late:06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00',
ASC_Time_Up_WE_Holiday => 'ASC_Time_Up_WE_Holiday:06:00,06:15,06:30,06:45,07:00,07:15,07:30,07:45,08:00,08:15,08:30,08:45,09:00,09:15,09:30,09:45,10:00'}
attr ASC_Jalousien_Times room Jalousien</pre>

[[Bild:ASC Jalousien Level.JPG|thumb|right|Beispiel]]
<pre style="width:65%;word-break: break-all;word-wrap: break-word;"> define Jalousien_Level readingsGroup <Gerät>,<Closed_Pos>,<Open_Pos>,<Comfort_Pos>,<Ventilate_Pos>,<PrivacyDown_Pos>,<Shading_Pos> (.*_Jalousie.*):?ASC_Closed_Pos,?ASC_Open_Pos,?ASC_ComfortOpen_Pos,?ASC_Ventilate_Pos,?ASC_PrivacyDown_Pos,?ASC_Shading_Pos
attr Jalousien_Level commands { ASC_Closed_Pos => 'ASC_Closed_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99',
ASC_Open_Pos => 'ASC_Open_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99',
ASC_ComfortOpen_Pos => 'ASC_ComfortOpen_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99',
ASC_Ventilate_Pos => 'ASC_Ventilate_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99',
ASC_PrivacyDown_Pos => 'ASC_PrivacyDown_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99',
ASC_Shading_Pos => 'ASC_Shading_Pos:0,10,20,30,35,40,45,50,55,60,65,70,75,80,85,90,95,99'}
attr Jalousien_Level room Jalousien</pre>

== Einrichtungsbeispiel ==
=== Zielsetzung und Vorgaben ===
Es sollen alle Rollläden und Jalousien in einem Haus innerhalb bestimmter zeitlicher Grenzen Morgens und Abends sonnenstandsabhängig gefahren werden, an den Wochenenden und an Ferientagen soll etwas später geöffnet werden. Es sind Tür- und Fensterkontakte vorhanden (Türkontakte: twoState, Fensterkontakte: threeState), wobei bei jeder Öffnung ein eventuell geschlossener Rollladen geöffnet werden soll. Bei allen Rollladenaktoren, Tür- und Fensterkontakten handelt es sich um CUL_HM-Geräte.

=== Vorarbeiten ===
Im global-Device sind Angaben zu latitude und longitude vorhanden, holiday2we wie folgt<ref>''ferien'' ist eine automatisiert erstellte holiday-Datei nach diesem {{Link2Forum|Topic=85759|Message=885883|LinkText=Foren-Beitrag}}.</ref>:
attr global holiday2we bw,ferien
Weitere Angaben benötigen wir zunächst nicht, die Festlegung eines Astro-Devices erfolgt hier erst im Rahmen der Beschattung.
Dann erfolgt das ''Define des ASC-Devices'' wie oben beschrieben:
<code>define Rollladenautomatik AutoShuttersControl</code>
Folgen die einzubindenden Rollladenaktoren einem einheitlichen Namensschema, können diese sodann z.B. mit
attr (Jalousie|Rollladen)_.* ASC 2
auf einen Rutsch mit dem passenden ASC-Typ gekennzeichnet werden. Dann verteilen wir mir
set Rollladenautomatik scanForShutters
die nachfolgend weiter zu bearbeitenden Attribute.
=== Schließen morgens und abends ===
{{Randnotiz|RNTyp=g|RNText=Alternative: Fahren nach brightness:
Will man insgesamt oder nur an einzelnen Rollläden stattdessen helligkeitsgesteuert fahren, muß für jeden Rollladen ein Helligkeitssensor definiert und entweder zentral oder am einzelnen Rollladen jeweils ein Höchst- bzw. Mindestwert festgelegt werden (''ASC_BrightnessMinVal'' etc.), bei dessen Überschreitung geöffnet bzw. Unterschreitung geschlossen werden soll.}}
==== Konfiguration des ASC-Devices ====
Da wir sonnenstandsabhängig Fahrzeiten wollen, legen wir erst einmal fest, dass dies morgens und abends berücksichtigt werden soll:
<pre>
attr Rollladenautomatik ASC_autoAstroModeEvening CIVIL
attr Rollladenautomatik ASC_autoAstroModeMorning CIVIL
attr Rollladenautomatik ASC_autoShuttersControlEvening on
attr Rollladenautomatik ASC_autoShuttersControlMorning on
</pre>
Aus der Angabe ''CIVIL'' und den Vorgaben in den einzelnen Rollladen wird dabei mit Hilfe von [[SUNRISE_EL]] die effektive Fahrzeit berechnet, dort finden sich auch weitere Hinweise, zu den meisten anderen Optionen für die ersten beiden Attribute.
Bei allen Fensteröffnungen soll auf eine Lüften-Position gefahren werden, also schalten wir diese Funktion ebenfalls zentral an<ref>Sonst wird bei threeState-Sensoren nur bei ''tilted'' auf die in ''ASC_Ventilate_Pos'' gefahren.</ref>:
attr Rollladenautomatik ASC_autoShuttersControlComfort on
Zuletzt legen wir noch einen Temperatur-Sensor fest. Dieser wird beim Frostschutz sowie bei der Beschattung berücksichtigt.
<pre>
attr Rollladenautomatik ASC_temperatureSensor Aussentemperatur_Nord
attr Rollladenautomatik ASC_temperatureReading temperature
attr Rollladenautomatik ASC_freezeTemp 3
</pre>

tbd:
* Rain
* Wind
==== Konfiguration der Rollladendevices ====
===== Fahrzeiten =====
Zur Konfiguration der Fahrzeiten bietet es sich an, eine ReadingsGroup zu nutzen, wie unter [[#Hilfsmittel|Hilfsmittel]] dargestellt. Alternativ kann man die Zeiten auch manuell in den einzelnen Rollläden hinterlegen.
===== Bewohner =====
Wird ein Raum von einer oder mehreren bestimmten Person/en bewohnt oder gibt es ein Sammel-Gerät für mehrere Bewohner, kann dies mit den Attributen ''ASC_Roommate_Device'' und ''ASC_Roommate_Reading'' einem Rollladen zugeordnet werden. Ist einer der Bewohner ''asleep'', wird morgens erst geöffnet, wenn auch der letzte Roommate nicht mehr ''asleep'' ist.
===== Fensterkontakte =====
Dann werden ggf. vorhandene Fensterkontakte zugeordnet und der Typ festgelegt, wobei im Falle von threeState-Sensoren das übergreifende ''ASC_autoShuttersControlComfort'' beachtet wird, wobei dann bei vollstäniger Öffnung des Fensters auf den in ''ASC_ComfortOpen_Pos'' festgelegten Wert gefahren wird.
===== Frostschutz =====
Zuletzt können die Attribute ''ASC_Antifreeze'' und ''ASC_Antifreeze_Pos'' festgelegt werden, wenn die Frostschutzfunktion aktiviert werden soll.
=== Beschattung ===
==== Konfiguration des ASC-Devices ====
Benötigt werden Informationen zum Sonnenstand. Hierfür wird ein astro- oder twilight-Device benötigt. Ist ein solches definiert, wird dies - ggf. auch nach einem Neustart vom Modul automatisch erkannt und in das Attribut ''ASC_twilightDevice'' eingetragen. Wir legen daher zunächst ein entsprechendes Device an bzw. passen die Angabe ggf. an, wenn ein anderes als das eingetragene genutzt werden soll.
Weiter ist ein Temperatursensor für die Beschattung festzulegen (''ASC_temperatureSensor.*''-Attribute) wie bereits oben beschrieben.

==== Konfiguration der Rollladendevices ====
Zum einen legt man einen Helligkeitssensor fest (''ASC_Brightness_Sensor'' und ''ASC_Brightness_Reading''). Dieser ist der eigentliche Trigger. Nur, wenn sich der Brightness Wert ändert, werden Azimut, Elevation, Temperatur und die Ein- und Ausfallswinkel ausgelesen und/oder berechnet und basierend auf diesen Werten entschieden ob shading in oder shading out stattfinden soll, die Schwellwerte werden in ''ASC_Shading_StateChange_Sunny'' (Beschattung soll eingeschaltet werden) und ''ASC_Shading_StateChange_Cloudy'' (Beschattung soll beendet werden) festgelegt, wobei immer nur gefahren wird, wenn auch alles andere - insbesondere die Mindesthöhe des Sonnenstands (''ASC_Shading_Min_Elevation'') und die Mindesttemperatur ''ASC_Shading_Min_OutsideTemperature'' - passt.
Dann sind die Winkelangaben festzulegen, ggf. kann ein Kompass zu Hilfe genommen werden (''ASC_Shading_Direction'' ist die Richtung des Fensters, 90 Grad entspricht Ost, 180 Grad Süden, ''ASC_Shading_Angle_Left'' ist der Sonneneintritt ins Zimmer, wird von -Direction abgezogen, ''ASC_Shading_Angle_Right'' hat diesselbe Funktion für den Austrittswinkel.

=== Weitere Funktionen ===
==== Privacy ====
Werden hierfür Werte festgelegt, werden die betreffenden Rollläden die festgelegte Zeit vor dem abendlichen Schließen vorab teilweise geschlossen. Dies kann z.B. gewünscht sein, um Rollläden zur Straße hin mit viel Fußgängerverkehr zwar nicht vollständig abzudunkeln, aber gleichzeitig zu verhindern, dass von außen in Wohnräume geschaut werden kann, sobald dort das Licht angeschaltet wird
==== BlockingTime====
Bewirkt, dass nach einer manuellen Fahrt wird eine vom ASC Modul initiierte Fahrt zunächst ausgesetzt wird, bis die im Attribute angegebene Zeit überschritten ist. Erst dann wird eine dann vom ASC Modul initiierte Fahrt tatsächlich durchgeführt.
Genau so wird ein hochfahren eines Rollos durch das ASC Modul nicht mehr ausgeführt wenn es innerhalb der Zeit von ASC_BlockingTime_beforNightClose und das runterfahren wird nicht mehr erfolgen wenn es innerhalb von ASC_BlockingTime_beforDayOpen ist.
Beispiel: Meine Tochter geht früh aus Haus und Ihre Rollos sind nicht hoch gefahren. Diese fahren auch nicht mehr hoch da die ausschließlich bei home (anwesend) fahren sollen. Nun kommt sie am Nachmittag um 16:23 Uhr nach Hause, eigentlich sollten nun die Rollos fahren. Doch die Sonnenuntergangsfahrt (schließen) wäre schon 16:51 Uhr und damit innerhalb der 3600 ASC_BlockingTime_beforNightClose. Die Rollos bleiben also unten. Es lohnt sich für die paar Minuten einfach nicht mehr.
==== wiggle====
Mit einem <code>set <ASC-Device> wiggle</code> können alle Rollladen mit einem entsprechenden Attribut zu einer kurzen Fahrt veranlasst werden, nach Ablauf von einer Minute wieder um denselben Wert zurück. Dabei wird jeweils in die Richtung gefahren, die den weiteren Weg ermöglicht. Wenn also zu 70% geschlossen ist, wird der Rollladen hoch fahren.
==== Partymode ====
Dieser wird am ASC-Device selbst aktiviert mittels <code>set <ASC-Device> partyMode on</code>. Alle Rollladen-Devices, welche das Attribut ''ASC_Partymode'' auf ''on'' gestellt haben, werden nicht mehr gesteuert. Der letzte Schaltbefehl, der durch ein Fensterevent oder Bewohnerstatus an die Rollläden gesendet wurde, beim Beenden des Modus durch <code>set ASC-Device partyMode off</code> ausgeführt.
==== lock-out ====
(tbd auch hier: Doku ist etwas verteilt, könnte man im Wiki jeweils unter einem eigenen Unterabschnitt im Zusammenhang darstellen)

==== SelfDefense ====
Das bei einem absent nur da die Rollläden geschlossen werden wo das Fenster vergessen wurde zu schließen.
Beim wechsel in gone wird nur an den makierten Terassentüren (''ASC_ShuttersPlace terrace'') der Rollladen runter gefahren.
Weitere Attribute dazu: ''ASC_Self_Defense_Exclude''

== Sonstige Hinweise ==
* Werden Attribute geändert, kann es vereinzelt vorkommen, dass das ASC-Modul dies nicht mitbekommt und das tatsächliche Verhalten nicht den Erwartungen entspricht. In so einem Fall empfielt es sich, das NOTIFYDEV nochmals aufbauen zu lassen. Dazu werden zunächst mit <code>set <ASC-Modul> expert 1</code> erweiterte Informationen bezüglich des NotifyDevs unter set und get aktiviert und anschließend ein <code>set <ASC-Modul> createNewNotifyDev</code> ausgeführt.

== Weblinks ==
* {{Link2Forum|Topic=92628|LinkText="Thread zum Modul im Forum"}}
* {{Link2Forum|Topic=90751|LinkText="Thread zur Entwicklung im Forum"}}
* {{Link2Forum|Topic=73964|LinkText="Thread zu den Scripten von user cluni"}}, die der Entwicklung des Moduls zugrunde liegen

<references />

[[Kategorie:Code Snippets]]
[[Kategorie:Rollladensteuerung]]

Wochenende, Feiertage und Schulferien

2019-05-01T09:01:18Z

ChristophMorrison:

FHEM bietet die Möglichkeit, Komponenten in Abhängigkeit von Wochenenden und Schulferien sowie Feiertagen zu steuern. Hier soll beschrieben werden, wie Schulferien einbezogen werden.

== Wochenendermittlung mit $we ==
Um am Wochenende (Samstag und Sonntag) länger schlafen zu können, kann diese Steuerung durch Nutzung der Variable ''$we'' erweitert werden.
Diese hat am Wochenende den Wert ''1'', an sonstigen Tagen den Wert ''0''. In if-Abfragen wird die 0 als ''false/falsch'' interpretiert, andere numerische Werte als ''true/wahr''. Man kann mittels ''if ($we)'' also ganz einfach prüfen, ob Wochenende ist und entsprechend steuern (oder auch nicht).

Eine simple Rollladensteuerung um 7 Uhr morgens für jeden Tag sieht beispielsweise wie folgt aus:

define RolloHoch at *07:00 set Rollo hoch

Dieses Beispiel kann entsprechend ergänzt werden, so dass am Wochenende nicht um 7 Uhr das Rollo nach oben gefahren wird:

define RolloHoch at *07:00 { if (!($we)) { fhem("set Rollo hoch");; } }

Das ''!'' in der if-Abfrage negiert den dahinter folgenden Ausdruck in der Klammer, ist also "nicht Wochenende". Der Inhalt der äußeren geschweiften Klammern stellt echten Perl-Code dar (der hinter jeder Anweisung gerne ein Semikolon stehen hat, das in FHEM durch ein weiteres Semikolon [http://de.wikipedia.org/wiki/Maskierungszeichen maskiert/escaped] werden muss). Aus dem Perl-Code kann man mittels des Befehls ''fhem()'' wiederum FHEM-Code ausführen (hier der Befehl, um das Rollo nach oben zu fahren). Das (Doppel-)Semikolon ist in diesem Beispiel nicht zwingend notwendig, da es sich nur um eine einzige (und somit letzte) Anweisung handelt - man sollte sich jedoch aneignen, jede Anweisung im Perl-Code mit einem (Doppel-)Semikolon abzuschließen (eine schließende geschweifte Klammer stellt auch das Ende eine Anweisung bzw. eines Anweisungsblocks dar).

== Feiertage mittels holiday-Datei ==
Samstags und Sonntags bleibt das Rollo nun unten und man kann länger schlafen. Um diesen Komfort auch an Feiertagen zu haben, können in FHEM mittels ''holiday''-Dateien Feiertage definiert werden. Sinnvollerweise erstellt man sich für sein jeweiliges Bundesland eine eigene Datei, die Definitionen für feste Feiertage (z.B. Weihnachten oder der Tag der Deutschen Einheit) und solche in Abhängigkeit zu Ostern (z.B. Ostermontag oder Pfingsten, im Rheinland auch der Karneval) beinhaltet. Eine gutes Beispiel mit Erklärung findet sich in der [http://fhem.de/Heimautomatisierung-mit-fhem.pdf FHEM-Übersicht für Anfänger].
Nachdem beispielsweise die ''BW_Feiertag.holiday''-Datei im FHEM-Ordner erstellt/abgelegt wurde, kann diese in die Konfiguration eingebunden werden. Mittels ''holiday2we'' können die darin definierten Feiertage mit der Variable ''$we'' "verheiratet" werden. ''if ($we)'' ist danach immer wahr, sobald Wochenende oder ein Feiertag ist:

attr global holiday2we BW_Feiertag
define BW_Feiertag holiday

=== Mitgelieferte holiday-Dateien ===
FHEM liefert eine Reihe von vordefinierten holiday-Dateien mit:

* Dateien für die deutschen Bundesländer (abgekürzt laut [https://www.bmel-statistik.de/footernavigation/archiv/statistischer-monatsbericht/abkuerzungen-der-bundeslaender/ amtlicher Liste]), z.B. ''hh.holiday'' für Hamburg.
* Feiertage in Österreich: ''aut.holiday''
* Feiertage im Vereinigten Königreich und Nordirland: ''en.holiday''
* Islamische Feiertage: ''islam20xx.holiday''

== Feiertage mittels Internet-Kalender ==
{{Randnotiz|RNText=Alle x Stunden -wie hier dargestellt- einen unveränderten Jahres-Ferienkalender aus dem Internet erneut abzurufen ist nicht sinnvoll, da unnötige Abhängigkeiten des FHEM-Servers zur Verfügbarkeit des externen Servers entstehen. Zudem erzeugt dies unnötige Last auf dem externen Server. Besser ist es, nur einmal jährlich den Ferienkalender abzurufen und auf dem eigenen FHEM-Server zu speichern. Das Vorgehen ist beispielhaft in {{Link2Forum|Topic=36244|Message=299631}} beschrieben.}}
Theoretisch kann man in o.a. Datei auch seine persönlichen Urlaube oder die Schulferien definieren. Hier eignet sich jedoch die ''Calendar''-Funktion wesentlich besser. V.a. die Schulferien der einzelnen Bundesländer sind im Internet (z.B. unter [http://www.ferienwiki.de ferienwiki.de]) als iCal-Datei verfügbar und können wie folgt in FHEM eingebunden werden:

define BW_Ferien Calendar ical url https://www.ferienwiki.de/exports/ferien/2017/de/baden-wuerttemberg 86400

Das Intervall von 86400 Sekunden (entspricht 24 Stunden) für die Aktualisierung der Schulferien sollte im Normalbetrieb mehr als ausreichen. Wenn eigene Kalender (z.B. bei Google) für Urlaubstage genutzt werden, muss man individuell abwägen, wie oft dieser aktualisiert werden soll.

Um nun diesen Kalender nun nutzen zu können, benötigt FHEM einen ''dummy'', der entsprechend abgefragt werden kann:

define BW_Ferientag dummy
define BW_Ferien.notify notify BW_Ferien { \
fhem "set BW_Ferientag " . (ReadingsVal("BW_Ferien", "modeStart", "") =~ "ferien" ? 1: 0) }

Der ''BW_Ferientag'' ist in diesem Beispiel der angesprochene ''dummy'' und kann mittels ''Value("BW_Ferientag")'' abgefragt werden. Im ''notify'' wird der Wert gesetzt, sobald der Kalender aktualisiert wird: Eine ''1'' für einen Tag, an dem der Text "ferien" in einem Ereignis vorkommt, das sich im ''modeStart''Modus (vgl. {{Link2CmdRef|Anker=Calendar}} - ''The start time has passed but the end time of the calendar event is not yet reached.'') befindet, ansonsten ''0''. Das Vorkommen des Textes ist in den Ereignissen der oben genutzten Quelle immer der Fall.

Um ein Rollo nun weder am Wochenende, an Feiertagen, noch zu Schulferien morgens hochfahren zu lassen, lautet das Beispiel:

define RolloHoch at *07:00 { if ( !($we) && !(Value("BW_Ferientag")) ) { fhem("set Rollo hoch");; } }

Ausgehend von diesem Artikel ist unter [[Google-Kalender zur Steuerung von Dummies]] eine Vorgehensweise zur
Steuerung von FHEM mit dem Google-Kalender veröffentlicht.

Diese Methode unterstützt jedoch nicht die Feiertagserkennung des {{Link2CmdRef|Lang=de|Anker=DOIF|Label=DOIF}}-Moduls, speziell im Abschnitt {{Link2CmdRef|Lang=de|Anker=DOIF_Wochentagsteuerung|Label=Wochentagssteuerung}}. Hier wird nur der Status der ''$we''-Variable abgefragt und die Methode mit dem eigenen Holiday-Kalender empfohlen.

[[Kategorie:Code Snippets]] [[Kategorie:HOWTOS]]

Wochenende, Feiertage und Schulferien

2019-04-30T20:59:26Z

ChristophMorrison: Hinweis auf mitgelieferte holiday-Dateien

Holiday

2019-04-30T20:51:03Z

ChristophMorrison: Weiterleitungsziel von "Wochenende, Feiertage und Schulferien" nach Wochenende, Feiertage und Schulferien geändert

#REDIRECT [[Wochenende, Feiertage und Schulferien]]

Holiday

2019-04-30T20:50:34Z

ChristophMorrison: Added redirect for holiday

#REDIRECT [["Wochenende, Feiertage und Schulferien"]]

FAQ

2019-01-17T11:24:22Z

ChristophMorrison:

== Zweck ==
Auf dieser Seite möchte ich Einträge zu FAQ (frequently asked questions, häufige Fragen) sammeln.

== Fragen? Antworten! ==
<dl>
<dt>Ich möchte ein Gerät x mal alle y Minuten starten, aber nur von xx:xx bis yy:yy.</dt>
<dd>Du möchtest eine [[Zeitschaltuhr]].<dd>


</dl>

[[Kategorie:Code Snippets]]

FAQ

2019-01-17T11:23:48Z

ChristophMorrison:

== Zweck ==
Auf dieser Seite möchte ich Einträge zu FAQ (frequently asked questions, häufige Fragen) sammeln.

== Fragen? Antworten! ==
<dl>
<dt>Ich möchte ein Gerät x mal alle y Minuten starten, aber nur von xx:xx bis yy:yy.</dt>
<dd>Siehe →[[Zeitschaltuhr]]<dd>


</dl>

[[Kategorie:Code Snippets]]

Benutzer Diskussion:ChristophMorrison

2019-01-17T11:23:22Z

ChristophMorrison: /* Willkommen! */

Hilf mit und erweitere die [[FAQ]]!

FAQ

2019-01-17T11:22:51Z

ChristophMorrison: Erste FAQ hinzugefügt

== Zweck ==
Auf dieser Seite möchte ich Einträge zu FAQ (frequently asked questions, häufige Fragen) sammeln.

== Fragen? Antworten! ==
<dl>
<dt>Ich möchte ein Gerät x mal alle y Minuten starten, aber nur von xx:xx bis yy:yy.</dt>
<dd>Siehe →[[Zeitschaltuhr]]<dd>


</dl>

Zeitschaltuhr

2019-01-17T09:53:04Z

ChristophMorrison:

== Anforderung ==
Eine Umwälzpumpe, die an einem FS20 Schalter hängt, soll zu bestimmten Tageszeiten alle 15 Minuten für jeweils 5 Minuten eingeschaltet werden - mit unterschiedlichen Zeiträumen je Wochentag.

== Lösungsansatz 1: at ==
Es wird der [http://fhem.de/commandref.html#at at-Befehl] verwendet.

Täglich zur gewünschten Startzeit wird geprüft, ob die Voraussetzungen erfüllt sind. Ist dies der Fall, wird die Pumpe n mal alle 15 Minuten für 5 Minuten eingeschaltet.
Die jeweilige Laufzeit der Pumpe wird durch on-for-timer in Sekunden angegeben (300 Sekunden).

* Täglich 17 Uhr bis 23 Uhr (6 Stunden = 24 Wiederholungen à 15 Minuten)
<nowiki>define PumpeAbendsStart at *17:00:00 {
{ fhem("define PumpeAbends at +*{24}00:15:00 set Umwaelzpumpe on-for-timer 300") }
}</nowiki>
* An Wochentagen 7 Uhr bis 9 Uhr (8 Wiederholungen), an Wochenenden 7 Uhr bis 17 Uhr (36 Wiederholungen)
<nowiki>define PumpeMorgensStart at *07:00:00 {
if (!$we) {
{ fhem("define PumpeMorgens at +*{8}00:15:00 set Umwaelzpumpe on-for-timer 300") }
}
else {
{ fhem("define PumpeMorgens at +*{36}00:15:00 set Umwaelzpumpe on-for-timer 300") }
}
}</nowiki>
== Lösungsansatz 2: at mit Prüflauf ==
Es wird ein dauerhafter Prüflauf genutzt, der alle 15 Minuten prüft, ob der Zeitpunkt der Ausführung erreicht ist.

* An Wochentagen 7 Uhr bis 9 Uhr
<nowiki>define pumpe_wd78 at +*00:15 { fhem("set Umwaelzpumpe on-for-timer 300") if(!$we && $hour>=7 && $hour<9) }</nowiki>

== Lösungsansatz 3: RandomTimer ==
Als (einfache) Alternative kann auch das Hilfsmodul [[RandomTimer]] verwendet werden.

== Lösungsansatz 4: WeekdayTimer ==
Alternativ kann das Hilfsmodul [[WeekdayTimer]] genutzt werden.

== Lösungsansatz 5: DOIF ==
Siehe [https://fhem.de/commandref_DE.html#DOIF_Intervall-Timer DOIF Intervall-Timer]

== Weitere Beispiele ==
* [[AT zu einem absoluten Datum_ausführen|AT-Beispiele]]
* [[Wakeuplight|Wakeup-Light]]

[[Kategorie:Code Snippets]]

Zeitschaltuhr

2019-01-17T09:52:16Z

ChristophMorrison: Added DOIF example

== Anforderung ==
Eine Umwälzpumpe, die an einem FS20 Schalter hängt, soll zu bestimmten Tageszeiten alle 15 Minuten für jeweils 5 Minuten eingeschaltet werden - mit unterschiedlichen Zeiträumen je Wochentag.

== Lösungsansatz 1 ==
Es wird der [http://fhem.de/commandref.html#at at-Befehl] verwendet.

Täglich zur gewünschten Startzeit wird geprüft, ob die Voraussetzungen erfüllt sind. Ist dies der Fall, wird die Pumpe n mal alle 15 Minuten für 5 Minuten eingeschaltet.
Die jeweilige Laufzeit der Pumpe wird durch on-for-timer in Sekunden angegeben (300 Sekunden).

* Täglich 17 Uhr bis 23 Uhr (6 Stunden = 24 Wiederholungen à 15 Minuten)
<nowiki>define PumpeAbendsStart at *17:00:00 {
{ fhem("define PumpeAbends at +*{24}00:15:00 set Umwaelzpumpe on-for-timer 300") }
}</nowiki>
* An Wochentagen 7 Uhr bis 9 Uhr (8 Wiederholungen), an Wochenenden 7 Uhr bis 17 Uhr (36 Wiederholungen)
<nowiki>define PumpeMorgensStart at *07:00:00 {
if (!$we) {
{ fhem("define PumpeMorgens at +*{8}00:15:00 set Umwaelzpumpe on-for-timer 300") }
}
else {
{ fhem("define PumpeMorgens at +*{36}00:15:00 set Umwaelzpumpe on-for-timer 300") }
}
}</nowiki>
== Lösungsansatz 2 ==
Es wird ein dauerhafter Prüflauf genutzt, der alle 15 Minuten prüft, ob der Zeitpunkt der Ausführung erreicht ist.

* An Wochentagen 7 Uhr bis 9 Uhr
<nowiki>define pumpe_wd78 at +*00:15 { fhem("set Umwaelzpumpe on-for-timer 300") if(!$we && $hour>=7 && $hour<9) }</nowiki>

== Lösungsansatz 3 ==
Als (einfache) Alternative kann auch das Hilfsmodul [[RandomTimer]] verwendet werden.

== Lösungsansatz 4 ==
Alternativ kann das Hilfsmodul [[WeekdayTimer]] genutzt werden.

== Lösungsansatz 5: DOIF ==
Siehe [https://fhem.de/commandref_DE.html#DOIF_Intervall-Timer DOIF Intervall-Timer]

== Weitere Beispiele ==
* [[AT zu einem absoluten Datum_ausführen|AT-Beispiele]]
* [[Wakeuplight|Wakeup-Light]]

[[Kategorie:Code Snippets]]

Twilight

2019-01-16T14:39:09Z

ChristophMorrison: Updated maintainer info

{{Hinweis|'''End of Live der Yahoo Weather API''' 
Da die Yahoo Weather API zum 03.01.2019 abgeschaltet wurde, kann '''Twilight''' aktuell keine Wetterdaten beziehen!}}

{{Infobox Modul
|ModPurpose=Virtuelles Gerät zur Berechnung der Dämmerungszustände für eine gegebene Position
|ModType=h


|ModTechName=59_Twilight.pm
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModOwner=Christoph Morrison ({{Link2FU|17701|Forum}} / [[Benutzer_Diskussion:ChristophMorrison|Wiki]])
}}

[Twilight]] ist ein Hilfsmodul, das für eine über Koordinaten spezifizierte Position diverse Dämmerungszustände, Zeiten und die Helligkeit berechnet und als Readings bereitstellt. Darüber hinaus werden auch, sofern spezifiziert, über die Yahoo Wetter-ID Wetterinformationen bereitgestellt bzw. in die Berechnungen mit einbezogen.

== Voraussetzungen ==
Keine.

== Anwendung ==
=== Define ===
:<code>define <name> Twilight <latitude> <longitude> [<indoor_horizon> [<Weather_Position>]]</code>
Die Bedeutung der Parameter:
;latitude / longitude
:Geokoordinaten, für die die Werte berechnet werden sollen
;indoor_horizon
:Virtueller Horizont
;Weather_Position
:Yahoo Wetter-ID für den gewünschten Standort; der eingegebene Wert wird als "internal value" '''WEATHER''' gespeichert.

=== Attribute ===

=== Readings ===
Eine Auswahl der Readings, die das angelegte Twilight-Objekt enthält:
;sr*
:verschiedene Werte für den Sonnenaufgang ("'''s'''un'''r'''ise"): astronomisch, bürgerlich, nautisch, ...
;ss*
:verschiedene Werte für den Sonnenuntergang ("'''s'''un'''s'''et"): astronomisch, bürgerlich, nautisch, ...
;nextEvent
:Name des Ereignisses, das als nächstes eintreten wird (z. B. "ss_weather")
;nextEventTime
:Zeitpunkt, zu dem das (unter ''nextEvent'' benannte) nächste Ereignis eintreten wird
;light
:ein errechneter Helligkeitswert mit den folgenden möglichen Werten (zwischen 0 und 6):
:;0
::Völlige Dunkelheit; relativer Sonnenstand zum Horizont: -18°
:;1
::astronomische Dämmerung; relativer Sonnenstand zum Horizont: zwischen -12° und -18°
:;2
::nautische Dämmerung; relativer Sonnenstand zum Horizont: zwischen -6° und -12°
:;3
::bürgerliche Dämmerung; relativer Sonnenstand zum Horizont: zwischen 0° und -6°
:;4
::"indoor"-Dämmerung; Sonnenstand zwischen '''indoor_horizon''' (sofern der Wert ungleich Null ist) und 0°
:;5
::"Wetter"-Dämmerung; Sonnenstand zwischen '''indoor_horizon''' und einem virtuellen Wetter-Horizont (abhängig von der Angabe einer '''Weather_position''')
:;6
::"normales" Tageslicht
;azimuth
:Azimut; Horizontalwinkel des Sonnenstands (0°=Norden, 180°=Süden, usw.)
;elevation
:Höhe des Sonnenstands
;twilight
:Dämmerungswert, errechnet aus der Höhe des Sonnenstands. Der Wert geht von 0% bis 100% bei einem Sonnenstand zwischen -12° und 6° (also während der Dämmerungsphase).

=== Funktionen ===
:<code>twilight($twilight, $reading, $min, $max)</code>
Funktion im Modul, um bei der Dämmerungsberechnung Minimal-/Maximalwerte ("frühestens/spätestens") spezifizieren und das Ergebnis beispielsweise in einem <code>at</code> weiterverarbeiten zu können.

== Anwendungsbeispiel(e) ==
=== Kurzes Beispiel ===
Anwendung der Funktion ''twilight'' zur Zeitsteuerung:
:<code>define morgens at *{twilight("myTL","sr_indoor","7:30","9:00")} set Rollo on</code>
Dieses '''at''' wird morgens zum Zeitpunkt ''sr_indoor'' des Twilight Objekts ''myTL'' - aber frühestens um 7:30 und spätestens um 9:00 Uhr - dem Gerät ''Rollo'' einen ''on''-Befehl schicken. Das Objekt ''myTL'' muss natürlich vorher mit (beispielsweise)
:<code>define myTL Twilight 44.444444 8.888888 ...</code>
definiert worden sein.

=== Ausführliches Beispiel ===
[[Twilight Anwendungsbeispiel]] mit detaillierten Erläuterungen

[[Kategorie:Code Snippets]]

Weather

2019-01-04T16:37:30Z

ChristophMorrison:

{{Hinweis|'''End of Live der Yahoo Weather API''' 
Da die Yahoo Weather API zum 03.01.2019 abgeschaltet wurde, kann '''Weather''' keine Wetterdaten von Yahoo mehr beziehen!}}

{{SEITENTITEL:Weather}}
{{
Infobox Modul
|ModPurpose=Wettervorhersagen von Yahoo abfragen.
|ModType=d

|ModCmdRef=Weather
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModTechName=59_Weather.pm
|ModOwner=Dr. Boris Neubert
}}

Mit dem Modul [[Weather]] können aktuelle Wetterdaten und Wettervorhersagen für einen bestimmten Ort von der Yahoo-Wetter-API regelmäßig abgefragt werden.

== Anwendung ==
=== Define ===
siehe {{Link2CmdRef|Lang=de|Anker=Weatherdefine}}.

=== Attribute ===
siehe {{Link2CmdRef|Lang=de|Anker=Weatherattr}}.

== Anwendungsbeispiele ==
=== Beispiel zur Modul-Einrichtung ===
Zuerst einmal besuchen wir die [http://weather.yahoo.com Yahoo Wetterseite] und öffnen den Wetterbericht für die jeweilige Stadt (z.B. [http://weather.yahoo.com/germany/berlin/berlin-638242 Berlin]). In der URL des Wetterberichtes findet sich dann die sogenannte WOEID (WHERE-ON-EARTH-ID). Sie identifiziert die Wetterinfos, die FHEM abfragen soll. Für Berlin ist dies die Nummer 638242.

In der [[Konfiguration]] richten wir dann folgendes ein:

<pre>
# – Wetterdaten erfassen -
define MeinWetter Weather 638242 3600 de
attr MeinWetter room Wettervorhersage

# - Logfile für alle Wetter Daten (monatsweise getrennt) —
define FileLog_MeinWetter FileLog ./log/meinwetter-%Y-%m.log MeinWetter
attr FileLog_MeinWetter logtype text
attr FileLog_MeinWetter room Wettervorhersage

# — Wetter Icons in vertikaler Ansicht hinzufügen —
define weblink_meinwetter weblink htmlCode {WeatherAsHtml("MeinWetter",7)}
attr weblink_meinwetter room Wettervorhersage
</pre>

Das hat zur Folge, dass FHEM nun die Wetterdaten für Berlin (638242) jede Stunde (3600) neu abholt. Zudem wird eine vertikale Ansicht der Wetterdaten der nächsten 7 Tage erstellt. Die Anzeige erfolgt im Raum "Wettervorhersage".

=== Konfigurationsschwierigkeiten ===

Da Yahoo momentan auf mehreren Browsern Darstellungs-Schwierigkeiten hat, ist es schwer bis unmöglich, nach bestimmten Städten zu suchen (Search Box ist nicht erreichbar).

Für diesen Fall gibt es aber noch die Möglichkeit, die WOEID auf [https://www.computerhilfen.de/hilfen-64-422419-0.html Yahoo WOEID: So bekommt man die "Where on Earth" ID einer Stadt!] zu erhalten.
Erfolgreich gefunden habe ich diese Seite übrigens über den Trick einer Internet-Suche nach ''mehreren'' dominant bekannten Städte-IDs (oder vielleicht einfach Internet-Suche nach "WOEID").

== Links ==
* Weblink mit Stadtangabe für Wetter-Icons-Anzeige definieren: {{Link2Forum|Topic=31428|Message=267555}}
* Einrichtung einer automatische Aktualisierung der Wetter-Anzeige-Seite (Weblinks): {{Link2Forum|Topic=34581|Message=268957}}
* Anzahl der Icons definieren: {{Link2Forum|Topic=20481|Message=253464}}

Twilight Anwendungsbeispiel

2019-01-04T11:50:56Z

ChristophMorrison: Hinweis auf EoL der Yahoo Weather API

{{Hinweis|'''End of Live der Yahoo Weather API''' 
Da die Yahoo Weather API zum 03.01.2019 abgeschaltet wurde, kann '''Twilight''' aktuell keine Wetterdaten beziehen!}}

Das Modul [[Twilight]] errechnet verschiedene Dämmerungsphasen und kalkuliert daraus einen wetter- und dämmerungsabhängigen Lichtwert, der den Grad der Außenhelligkeit angibt. Hier soll an einem Beispiel der Einsatz dieses Moduls zur Steuerung eines Ambient-Lichtes und einer Vitrinenbeleuchtung gezeigt werden.

Ziel: eine indirekte Beleuchtung, z. B. im Wohnzimmer, soll, sobald es zu dämmern anfängt bzw. wetterabhängig schon früh "gefühlt" dunkler wird, eingeschaltet werden. In diesem Beispiel wird eine dimmbare indirekte Beleuchtung (ein LED-Lichtschlauch) verwendet. Die Helligkeit des Lichtschlauchs soll bei nur leichter Dämmerung maximal sein und soll sich dann bei Dunkelheit bis auf 20% reduzieren. Die Vitrinenbeleuchtung (ebenfalls LED) soll ebenfalls nur dann eingeschaltet sein, wenn es nicht taghell ist, da man die da sowieso nicht sieht. Nachts soll die Beleuchtung natürlich nicht an sein, dazu wird hier auf eine Variable "Anwesend" zurückgegriffen, die beim Autor als Indikator für Nacht und Abwesenheitsbetrieb verwendet wird. Dies kann individuell angepasst werden. Anwesend=2 bedeutet "Die Bewohner sind im Bett" und Anwesend=4 bedeutet "Die Bewohner sind abwesend".

Neben der automatischen Beleuchtung soll auch ein manuelles Eingreifen möglich sein. So kann über einen Wandtaster sowohl das AmbientLight als auch die Vitrinenbeleuchtung ein- oder ausgeschaltet werden, wobei die Automatik nach einer bestimmten Zeit automatisch wieder greifen soll. Hier werden ein Homematic-Schaltaktor und ein Homematic-Dimmer verwendet, das Beispiel lässt sich leicht auf andere Komponenten übertragen.

Zur Realisierung wurden einige Perl-Schnipsel in ein externes Modul ausgelagert, weil dies wesentlich übersichtlicher ist als die Inline-Definition in der fhem.cfg. Als Basis kann das Modul 99_Utils.pm genommen werden. Der Autor hat diese Datei kopiert, das Modul umbenannt, und den zusätzlichen Code eingetragen.

== Definition des Twilight-Devices ==
Um überhaupt die Lichtwerte zur Verfügung zu haben, muss zunächst ein Twilight-Device erzeugt werden. Hierzu wird folgender Aufruf verwendet:

Syntax: <code>define <name> Twilight <Längengrad> <Breitengrad> <Indoor_Horizont> <Yahoo-Wetter-ID></code>

Beispiel für Helgoland:
<pre>
define T twilight 54.18258 7.885938 1 709403
</pre>

Hier beispielhaft eine Eingabe direkt per telnet in FHEM auf Port 7072

=== Code ===
<pre>
define T twilight 54.18258 7.885938 1 709403

list T
Internals:
CFGFN
DEF 54.18258 7.885938 1 709403
INDOOR_HORIZON 1
LATITUDE 54.18258
LONGITUDE 7.885938
NAME THelgo
NR 751
STATE 6
TYPE Twilight
WEATHER 709403
WEATHER_HORIZON 6
Readings:
2012-03-30 08:40:34 light 6
2012-03-30 08:40:34 nextEvent ss_weather
2012-03-30 08:40:34 nextEventTime 19:13:23
2012-03-30 08:40:34 nextUpdate 08:55:34
2012-03-30 08:40:34 sr 07:10:41
2012-03-30 08:40:34 sr_astro 04:57:56
2012-03-30 08:40:34 sr_civil 06:28:52
2012-03-30 08:40:34 sr_indoor 07:17:33
2012-03-30 08:40:34 sr_naut 05:45:13
2012-03-30 08:40:34 sr_weather 07:51:46
2012-03-30 08:40:34 ss 19:54:28
2012-03-30 08:40:34 ss_astro 22:07:13
2012-03-30 08:40:34 ss_civil 20:36:17
2012-03-30 08:40:34 ss_indoor 19:47:36
2012-03-30 08:40:34 ss_naut 21:19:56
2012-03-30 08:40:34 ss_weather 19:13:23
</pre>

Zu sehen ist hier die Übersicht der entsprechenden Dämmerungszeiten des aktuellen Tages (Details siehe FHEM {{Link2CmdRef|Anker=Twilight}}).

== Berechnung des Automatik-Wertes ==

In folgender Routine wird zunächst abhängig vom Lichtwert und der aktuellen Anwesenheit der Automatikwert für den Lichtschlauch und die Schrankbeleuchtung errechnet. Der Lichtschlauch ist ein Dimmer, erhält also Werte zwischen 0% und 100% und die Vitrine ist ein Schaltaktor, ist also entweder an oder aus.
<pre>
sub calc_a_schlauch{
my $licht=ReadingsVal("T","light","6");
my $anwesend=ReadingsVal("anwesend","state","4");
if($licht eq 6 || $anwesend eq 2 || $anwesend eq 4){
fhem "set a_schlauch 0" ;
fhem "set a_schrank off";
}elsif($licht<6 && $licht>3){
fhem "set a_schlauch 100";
fhem "set a_schrank on";
}elsif($licht>2 && $licht<5){
fhem "set a_schlauch 40";
fhem "set a_schrank on";
}elsif($licht<3){
fhem "set a_schlauch 20";
fhem "set a_schrank on";
}
}
</pre>

Die Ausgangsbedingungen "light" und "anwesend" werden zu Beginn abgefragt. In der darauffolgenden IF-Anweisung wird dann je nach Lichtstärke ein Wert für die beiden Automatikwerte gesetzt. Zu beachten ist, dass die Devices a_schlauch und a_schrank Dummy-Devices sind (siehe fhem.cfg unten). Hier wird noch nicht direkt geschaltet sondern nur ein Wert berechnet und zwischengespeichert.

== Manuelle Schaltung Vitrine ==

Zur manuellen Schaltung wird durch das Drücken eines Tasters folgender Schnipsel ausgeführt, der dann den neuen Manuell-Wert berechnet:
<pre>
sub calc_m_schrank{
my $aktuell = ReadingsVal("m_schrank","state","auto");
my $auto = ReadingsVal("a_schrank","state","off");
if($aktuell eq "off" || ($aktuell eq "auto") && $auto eq "off"){
fhem "set m_schrank on";
}else{
fhem "set m_schrank off";
}
}
</pre>
Die aktuellen Werte für Manuell und Automatik werden zunächst aus den Dummy-Devices abgefragt. Jetzt gibt es zwei Möglichkeiten. Wenn die Vitrine gerade in dem Zustand ist, dass sie schon manuell ausgeschaltet wurde (also $aktuell eq "off"), dann muss sie jetzt eingeschaltet werden. Dies muss auch dann passieren, wenn man gerade im Automatikmodus ist, und eben dieser gerade auf "off" steht. Dies ist wichtig, damit für den Anwender, dem nicht klar ist, in welcher Betriebsart die Beleuchtung gerade ist, bei jedem Tasterdruck auch ein sichtbarer Schaltvorgang ausgelöst wird.

== Manuelle Schaltung LED-Schlauch ==

Die manuelle Schaltung des LED-Schlauchs ist noch etwas aufwendiger, da mehrere Dimmerstufen angefahren werden sollen:
<pre>
sub calc_m_schlauch{
my $aktuell = ReadingsVal("m_schlauch","state",0);
my $auto = ReadingsVal("a_schlauch","state",0);
if($aktuell==0 || ($aktuell==-1 && $auto==0)){
fhem "set m_schlauch 100";
}elsif($aktuell==100){
fhem "set m_schlauch 30";
}elsif($aktuell==30 || ($aktuell==-1 && $auto>0)){
fhem "set m_schlauch 0";
}else{
fhem "set m_schlauch 0";
}
}
</pre>

Das Prinzip ist wie bei der Vitrine. Da hier mit numerischen Werten gearbeitet wird, ist die Bedeutung "Automatik" nicht als "auto" definiert sondern als Zahlenwert "-1". D.h. der Wert für "m_schlauch" kann zwischen -1 und 100 schwanken, wobei im Bereich 0-100 ein manueller Wert gesetzt wird und bei "-1" die Automatik greifen soll.

In der IF-Abfrage wird zunächst der Fall behandelt, dass das Licht komplett aus ist. Dies ist entweder der Fall, wenn es manuell aus ist oder die Automatik greift und diese aber auch auf "0" ist. Der zweite Zweig schaltet den manuellen Wert auf 30 runter, wenn dieser gerade auf 100 ist. In allen anderen Fällen wird das Licht im nächsten Schritt manuell ausgeschaltet.

== Schalten der Aktoren ==

Letztlich müssen natürlich die Aktoren tatsächlich geschaltet werden. Dazu wird folgende "Treiber"-Routine genutzt, die die manuellen und automatischen Werte logisch kombiniert:
<pre>
sub drive_schrank_schlauch{
my $dimmer=dimvalue(ReadingsVal("dim_schlauch","state",0));
my $man=ReadingsVal("m_schlauch","state",0);
my $auto=ReadingsVal("a_schlauch","state",0);
my $newvalue;
my $zeit=60;

if($man==-1){
$newvalue=$auto;
}else{
$newvalue=$man;
$zeit=5;
}
if($dimmer ne $newvalue){
fhem "set dim_schlauch ".$newvalue." 84000 ".$zeit;
}
my $schrank=ReadingsVal("akt_schrank","state","off");
$man=ReadingsVal("m_schrank","state","auto");
$auto=ReadingsVal("a_schrank","state","off");
if($man eq "auto"){
$newvalue=$auto;
}else{
$newvalue=$man;
}
if($schrank ne $newvalue){
fhem "set akt_schrank ".$newvalue;
}

}
</pre>

Hier wird nun zuerst der LED-Schlauch und dann der Schrank behandelt. Zunächst wird sowohl der aktuelle Wert des tatsächlichen Aktors (hier: dim_schlauch) als auch die Manuell- und Automatik-Werte abgefragt. Die Variable $newvalue soll den neuen Schaltwert erhalten. Dies wird deswegen eingesetzt, um einen Schaltbefehl nur dann über Funk zu senden, wenn sich der Zustand geändert hat. Die Variable $zeit wird hier genutzt, um beim automatischen Schalten den Dimmer sehr langsam fahren zu lassen, so dass es zu keiner abrupten merklichen Helligkeitsänderung kommt. Dies geht nur mit Homematic-Dimmern.

In der folgenden IF-Abfrage wird geklärt, ob der Dimmer im manuellen oder automatischen Modus betrieben wird. Dementsprechend wird $newvalue gesetzt. Bei manuellem Betrieb wird die Zeit auf 5 Sekunden runtergesetzt, denn hier soll eine merkliche Helligkeitsänderung in kurzer Zeit nach dem Betätigen des Tasters erfolgen. Stellt sich dann in der kommenden Abfrage heraus, dass der aktuelle Wert des Aktors noch nicht dem von $newvalue entspricht, wird ein tatsächlicher Schaltvorgang ausgelöst. Die Zahl 84000 ist die Einschaltzeit des Dimmers (unwichtig hier, muss nur hoch genug sein, ist aus Sicherheitsgründen nicht auf 0=unendlich - so geht der Dimmer auch bei einem FHEM-Ausfall nach knapp 24 Stunden aus).
Im weiteren Verlauf wird die Vitrine nach dem gleichen Prinzip geschaltet, wobei hier keine Zeit sinnvoll ist.

=== fhem.cfg ===
In der fhem.cfg müssen, damit die Schnipsel funktionieren, neben dem Twilight-Device auch die Dummy-Devices, die beiden Aktoren, und entsprechende At-/Notify-Defines eingetragen werden, die dafür sorgen, dass die Code-Schnipsel ausgeführt werden. Die Definition der beiden Aktoren ist hier nicht aufgeführt und muss individuell eingetragen werden.

<pre>
define a_schlauch dummy
define m_schlauch dummy
define a_schrank dummy
define m_schrank dummy
define T twilight 54.18258 7.885938 1 709403
set m_schlauch -1
set m_schrank auto

define m_a_schlauch notify m_a_schlauch {calc_a_schlauch();;}
define n_abwesend_ambient notify anwesend {fhem "trigger m_a_schlauch";;}
define n_lightchange_ambient notify T:light.* {fhem "trigger m_a_schlauch";;}
define n_d_schlauch notify a_schlauch {drive_schrank_schlauch();;}
define n_d_schlauch2 notify m_schlauch {drive_schrank_schlauch();;}
define n_d_schrank notify a_schrank {drive_schrank_schlauch();;}
define n_d_schrank2 notify m_schrank {drive_schrank_schlauch();;}
define n_m_schlauch_reset notify m_schlauch {fhem "delete temp_at_m_schlauch_reset";;fhem "define temp_at_m_schlauch_reset at +01:00:00 set m_schlauch -1";;}
define n_m_schrank_reset notify m_schrank {fhem "delete temp_at_m_schrank_reset";;fhem "define temp_at_m_schrank_reset at +01:00:00 set m_schrank auto";;}
define n_m_schlauch notify taster_wohn:Btn1.off[^L]* {calc_m_schlauch();;}
define n_m_schrank notify taster_wohn:Btn2.on[^L]* {calc_m_schrank();;}
</pre>

<code>m_a_schlauch</code> ist ein Makro, was hier überflüssig erscheint, aber sinnvoll ist, wenn man einen Perl-Aufruf von verschiedenen Stellen aus antriggern will, so ist man unabängig vom tatsächlichen Inhalt.

Die Berechnung wird also immer dann angetriggert, wenn entweder der Anwesenheitsstatus oder der Lichtwert sich verändert haben. Die folgenden Notifys reagieren auf Werteänderungen der Automatik- und Manuell-Dummys. Die nächsten beiden Notifys (<code>n_m_schlauch_reset</code> und <code>n_m_schrank_reset</code>) sorgen dafür, dass bei einer Änderung der Manuell-Werte durch das Drücken von Tastern, etc. der Wert nach einer Stunde wieder auf Automatik zurückfällt. Die letzten beiden Notifys reagieren auf genau diese Taster, wobei hier ein Homematic-Wandtaster eingesetzt wird, bei dem nur auf einen kurzen Tastendruck reagiert werden soll.

Der bisherige Code sieht nicht vor, mit den Tastern auch frühzeitig wieder auf Automatik zurückzuschalten. Das kann z. B. mit einem zusätzlichen Taster gemacht werden:

<pre>
define n_tEingang_lichtReset notify taster_eingang:Btn1.offLong.* {lichtReset();;}
</pre>

Hier wird auf den langen Tastendruck eines anderen Tasters reagiert, wobei dieser Notify zündet, sobald man den Taster länger als 0,4 Sekunden festhält, also noch bevor dieser losgelassen wird. Der Code von lichtReset kann dann mehr tun, als nur die beiden hier beschriebenen Beleuchtungen auf Automatik zu setzen. Beispiel:
<pre>
sub lichtReset{
fhem "set m_schlauch -1";
fhem "set m_schrank auto";
fhem "set akt_treppe off";
fhem "set akt_eingang off";
fhem "set akt_esszimmer off";
}
</pre>

== yahoo - Condition Codes ==
<pre>
Condition code Beschreibung Internes Mapping in: sub Twilight_getWeatherHorizon
0 tornado 25
1 tropical storm 25
2 hurricane 25
3 severe thunderstorms 25
4 thunderstorms 20
5 mixed rain and snow 10
6 mixed rain and sleet 10
7 mixed snow and sleet 10
8 freezing drizzle 10
9 drizzle 10
10 freezing rain 10
11 showers 7
12 showers 7
13 snow flurries 7
14 light snow showers 5
15 blowing snow 10
16 snow 10
17 hail 6
18 sleet 6
19 dust 6
20 foggy 10
21 haze 6
22 smoky 6
23 blustery 6
24 windy 6
25 cold 6
26 cloudy 6
27 mostly cloudy (night) 5
28 mostly cloudy (day) 5
29 partly cloudy (night) 3
30 partly cloudy (day) 3
31 clear (night) 0
32 sunny 0
33 fair (night) 0
34 fair (day) 0
35 mixed rain and hail 7
36 hot 0
37 isolated thunderstorms 15
38 scattered thunderstorms 15
39 scattered thunderstorms 15
40 scattered showers 9
41 heavy snow 15
42 scattered snow showers 8
43 heavy snow 5
44 partly cloudy 12
45 thundershowers 6
46 snow showers 8
47 isolated thundershowers 8
not available 1
</pre>

== Zusammenhang STATE und light ==

STATE wird beim Twilight-Modul von 0 - 11 durchgezählt.

0 -> vor astronomischen Aufgang, 1 -> vor nautischem Aufgang, 2 -> vor zivilem Aufgang, 3 -> vor Sonnenaufgang, 4 -> vor Indoor-Aufgang, 5 -> vor "Wetter-Aufgang", 6 -> vor "Wetter-Untergang" (also den meisten Tag lang)

Bis hierher ist light = STATE. Von nun an wird light wieder weniger (es wird ja dunkler) aber STATE schreitet vor, um Sonnenuntergänge von -aufgängen unterscheidbar zu machen.

7 -> vor Indoor-Untergang, 8 -> vor Sonnenuntergang, 9 -> vor zivilem Untergang, 10 -> vor nautischem Untergang, 11 -> vor astronomischem Untergang

Bitte auch bedenken, dass in der Nordhälfte Deutschlands die Sonne astronomisch im Sommer ca. 6 Wochen lang nicht untergeht, State wird also nicht alle Werte durchlaufen und light wird nie 0 sein.

[[Kategorie:Examples]]

Twilight

2019-01-04T11:50:07Z

ChristophMorrison: Unbenutze Link-Sektion entfernt

{{Hinweis|'''End of Live der Yahoo Weather API''' 
Da die Yahoo Weather API zum 03.01.2019 abgeschaltet wurde, kann '''Twilight''' aktuell keine Wetterdaten beziehen!}}

{{Infobox Modul
|ModPurpose=Virtuelles Gerät zur Berechnung der Dämmerungszustände für eine gegebene Position
|ModType=h


|ModTechName=59_Twilight.pm
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModOwner=igami ({{Link2FU|4106|Forum}} / [[Benutzer_Diskussion:Igami|Wiki]])
}}

[Twilight]] ist ein Hilfsmodul, das für eine über Koordinaten spezifizierte Position diverse Dämmerungszustände, Zeiten und die Helligkeit berechnet und als Readings bereitstellt. Darüber hinaus werden auch, sofern spezifiziert, über die Yahoo Wetter-ID Wetterinformationen bereitgestellt bzw. in die Berechnungen mit einbezogen.

== Voraussetzungen ==
Keine.

== Anwendung ==
=== Define ===
:<code>define <name> Twilight <latitude> <longitude> [<indoor_horizon> [<Weather_Position>]]</code>
Die Bedeutung der Parameter:
;latitude / longitude
:Geokoordinaten, für die die Werte berechnet werden sollen
;indoor_horizon
:Virtueller Horizont
;Weather_Position
:Yahoo Wetter-ID für den gewünschten Standort; der eingegebene Wert wird als "internal value" '''WEATHER''' gespeichert.

=== Attribute ===

=== Readings ===
Eine Auswahl der Readings, die das angelegte Twilight-Objekt enthält:
;sr*
:verschiedene Werte für den Sonnenaufgang ("'''s'''un'''r'''ise"): astronomisch, bürgerlich, nautisch, ...
;ss*
:verschiedene Werte für den Sonnenuntergang ("'''s'''un'''s'''et"): astronomisch, bürgerlich, nautisch, ...
;nextEvent
:Name des Ereignisses, das als nächstes eintreten wird (z. B. "ss_weather")
;nextEventTime
:Zeitpunkt, zu dem das (unter ''nextEvent'' benannte) nächste Ereignis eintreten wird
;light
:ein errechneter Helligkeitswert mit den folgenden möglichen Werten (zwischen 0 und 6):
:;0
::Völlige Dunkelheit; relativer Sonnenstand zum Horizont: -18°
:;1
::astronomische Dämmerung; relativer Sonnenstand zum Horizont: zwischen -12° und -18°
:;2
::nautische Dämmerung; relativer Sonnenstand zum Horizont: zwischen -6° und -12°
:;3
::bürgerliche Dämmerung; relativer Sonnenstand zum Horizont: zwischen 0° und -6°
:;4
::"indoor"-Dämmerung; Sonnenstand zwischen '''indoor_horizon''' (sofern der Wert ungleich Null ist) und 0°
:;5
::"Wetter"-Dämmerung; Sonnenstand zwischen '''indoor_horizon''' und einem virtuellen Wetter-Horizont (abhängig von der Angabe einer '''Weather_position''')
:;6
::"normales" Tageslicht
;azimuth
:Azimut; Horizontalwinkel des Sonnenstands (0°=Norden, 180°=Süden, usw.)
;elevation
:Höhe des Sonnenstands
;twilight
:Dämmerungswert, errechnet aus der Höhe des Sonnenstands. Der Wert geht von 0% bis 100% bei einem Sonnenstand zwischen -12° und 6° (also während der Dämmerungsphase).

=== Funktionen ===
:<code>twilight($twilight, $reading, $min, $max)</code>
Funktion im Modul, um bei der Dämmerungsberechnung Minimal-/Maximalwerte ("frühestens/spätestens") spezifizieren und das Ergebnis beispielsweise in einem <code>at</code> weiterverarbeiten zu können.

== Anwendungsbeispiel(e) ==
=== Kurzes Beispiel ===
Anwendung der Funktion ''twilight'' zur Zeitsteuerung:
:<code>define morgens at *{twilight("myTL","sr_indoor","7:30","9:00")} set Rollo on</code>
Dieses '''at''' wird morgens zum Zeitpunkt ''sr_indoor'' des Twilight Objekts ''myTL'' - aber frühestens um 7:30 und spätestens um 9:00 Uhr - dem Gerät ''Rollo'' einen ''on''-Befehl schicken. Das Objekt ''myTL'' muss natürlich vorher mit (beispielsweise)
:<code>define myTL Twilight 44.444444 8.888888 ...</code>
definiert worden sein.

=== Ausführliches Beispiel ===
[[Twilight Anwendungsbeispiel]] mit detaillierten Erläuterungen

[[Kategorie:Code Snippets]]

Twilight

2019-01-04T11:46:51Z

ChristophMorrison: Hinweis auf EOL der Yahoo Weather API

{{Hinweis|'''End of Live der Yahoo Weather API''' 
Da die Yahoo Weather API zum 03.01.2019 abgeschaltet wurde, kann '''Twilight''' aktuell keine Wetterdaten beziehen!}}

{{Infobox Modul
|ModPurpose=Virtuelles Gerät zur Berechnung der Dämmerungszustände für eine gegebene Position
|ModType=h


|ModTechName=59_Twilight.pm
|ModForumArea=Unterstützende Dienste/Wettermodule
|ModOwner=igami ({{Link2FU|4106|Forum}} / [[Benutzer_Diskussion:Igami|Wiki]])
}}

[Twilight]] ist ein Hilfsmodul, das für eine über Koordinaten spezifizierte Position diverse Dämmerungszustände, Zeiten und die Helligkeit berechnet und als Readings bereitstellt. Darüber hinaus werden auch, sofern spezifiziert, über die Yahoo Wetter-ID Wetterinformationen bereitgestellt bzw. in die Berechnungen mit einbezogen.

== Voraussetzungen ==
Keine.

== Anwendung ==
=== Define ===
:<code>define <name> Twilight <latitude> <longitude> [<indoor_horizon> [<Weather_Position>]]</code>
Die Bedeutung der Parameter:
;latitude / longitude
:Geokoordinaten, für die die Werte berechnet werden sollen
;indoor_horizon
:Virtueller Horizont
;Weather_Position
:Yahoo Wetter-ID für den gewünschten Standort; der eingegebene Wert wird als "internal value" '''WEATHER''' gespeichert.

=== Attribute ===

=== Readings ===
Eine Auswahl der Readings, die das angelegte Twilight-Objekt enthält:
;sr*
:verschiedene Werte für den Sonnenaufgang ("'''s'''un'''r'''ise"): astronomisch, bürgerlich, nautisch, ...
;ss*
:verschiedene Werte für den Sonnenuntergang ("'''s'''un'''s'''et"): astronomisch, bürgerlich, nautisch, ...
;nextEvent
:Name des Ereignisses, das als nächstes eintreten wird (z. B. "ss_weather")
;nextEventTime
:Zeitpunkt, zu dem das (unter ''nextEvent'' benannte) nächste Ereignis eintreten wird
;light
:ein errechneter Helligkeitswert mit den folgenden möglichen Werten (zwischen 0 und 6):
:;0
::Völlige Dunkelheit; relativer Sonnenstand zum Horizont: -18°
:;1
::astronomische Dämmerung; relativer Sonnenstand zum Horizont: zwischen -12° und -18°
:;2
::nautische Dämmerung; relativer Sonnenstand zum Horizont: zwischen -6° und -12°
:;3
::bürgerliche Dämmerung; relativer Sonnenstand zum Horizont: zwischen 0° und -6°
:;4
::"indoor"-Dämmerung; Sonnenstand zwischen '''indoor_horizon''' (sofern der Wert ungleich Null ist) und 0°
:;5
::"Wetter"-Dämmerung; Sonnenstand zwischen '''indoor_horizon''' und einem virtuellen Wetter-Horizont (abhängig von der Angabe einer '''Weather_position''')
:;6
::"normales" Tageslicht
;azimuth
:Azimut; Horizontalwinkel des Sonnenstands (0°=Norden, 180°=Süden, usw.)
;elevation
:Höhe des Sonnenstands
;twilight
:Dämmerungswert, errechnet aus der Höhe des Sonnenstands. Der Wert geht von 0% bis 100% bei einem Sonnenstand zwischen -12° und 6° (also während der Dämmerungsphase).

=== Funktionen ===
:<code>twilight($twilight, $reading, $min, $max)</code>
Funktion im Modul, um bei der Dämmerungsberechnung Minimal-/Maximalwerte ("frühestens/spätestens") spezifizieren und das Ergebnis beispielsweise in einem <code>at</code> weiterverarbeiten zu können.

== Anwendungsbeispiel(e) ==
=== Kurzes Beispiel ===
Anwendung der Funktion ''twilight'' zur Zeitsteuerung:
:<code>define morgens at *{twilight("myTL","sr_indoor","7:30","9:00")} set Rollo on</code>
Dieses '''at''' wird morgens zum Zeitpunkt ''sr_indoor'' des Twilight Objekts ''myTL'' - aber frühestens um 7:30 und spätestens um 9:00 Uhr - dem Gerät ''Rollo'' einen ''on''-Befehl schicken. Das Objekt ''myTL'' muss natürlich vorher mit (beispielsweise)
:<code>define myTL Twilight 44.444444 8.888888 ...</code>
definiert worden sein.

=== Ausführliches Beispiel ===
[[Twilight Anwendungsbeispiel]] mit detaillierten Erläuterungen

== Links ==
* ...

[[Kategorie:Code Snippets]]

Luftdaten.info/Feinstaub

2018-12-28T17:49:44Z

ChristophMorrison:

{{Infobox Modul
|ModPurpose=Collect data from the Lufdaten.info project
|ModType=d
|ModCmdRef=LuftdatenInfo
|ModForumArea=Bastelecke
|ModFTopic=66674
|ModTechName=59_LuftdatenInfo.pm
|ModOwner=igami ({{Link2FU|4106|Forum}} / [[Benutzer:no_Legend|Wiki]])
}}
'''LuftdatenInfo''' ist ein Modul, das Sensor-Daten des Projektes [http://luftdaten.info/ luftdaten.info] in FHEM abrufbar macht.
Es können lokale oder entfernte Sensoren abgefragt werden.

== Sensor bauen ==
Der Bau eines Sensors wird auf der [http://luftdaten.info/feinstaubsensor-bauen/ Projektseite] beschrieben.
Die Kosten belaufen sich - je nach Bezugsquelle der einzelnen Bauteile und Bauform - auf ca. 30-50 €.

Zwei kurze Videos zum Aufbau und Flashen des Sensor sind u.a. auf Youtube zu finden:
* [https://youtu.be/8oLCTeCfabU Luftdaten.info Feinstaubsensor selber bauen]
* [https://youtu.be/NK3E083WayM luftdaten.info Feinstaubsensor NodeMCU flashen unter Windows]

== Datenschutz ==
In den Standard-Einstellung der Software werden die Messwerte zu der Projektseite hochgeladen und dort, nach dem man den Maintainern des Projekts eine E-Mail mit weiteren Daten hat zukommen lassen, auf einer [http://deutschland.maps.luftdaten.info/ Karte] dargestellt. Dazu sind die "letzten Schritte" auf der [https://luftdaten.info/feinstaubsensor-bauen/ Anleitungsseite] ganz unten zu befolgen.

Sollte keine Übertragung der Daten gewünscht sein, lassen sich die Geräte auch ausschließlich lokal betreiben und nicht von Fremden auslesen. Zumindest den Betreibern der Seite ist die Verknüpfung von Gerät zu Standort bekannt, ggf. lassen sich über die ermittelten Sensordaten auch genauere Standortdaten ermitteln.

== Daten nutzen ==
'''LuftdatenInfo''' unterstützt folgende drei Betriebsmodi:

=== Entfernte Abfrage ===
Mit <code>defmod <name> LuftdatenInfo remote <SensorID1> [<SensorID2> ..]</code> können - auch fremde - entfernte Geräte von luftdaten.info abgefragt werden. Angelegt werden neben den Werten für PM2.5 und PM10 auch Ortsdaten (ungefähre Latitude, ungefähre Longitude und Postleitzahl + Stadt). Weitere Sensoren eines Gerätes kann man ggf. durch Hochzählen der SensorID einbinden, z.B. liefert die SensorID 17382 Feinstaubdaten, SensorID 17383 liefert darüber hinaus auch noch Temperatur, Luftdruck und Luftfeuchte zurück. Andere Sensoren als der Feinstaubsensor werden aktuell auf luftdaten.info nicht angezeigt, müssen also erprobt werden.

=== Lokale Abfrage ===
Ein Gerät das Daten nicht an luftdaten.info oder eine der anderen Plattformen meldet, kann trotzdem lokal abgefragt werden. Dazu ist mit <code>defmod <name> LuftdatenInfo local <IP></code> das Gerät anzulegen. Es muss hier keine SensorID angegeben werden. Ohne weitere Einstellungen (<code>rawReadings</code>) liefert der Sensor hier allerdings keine Sensordaten! Diese kann man über den Slave-Modus einbinden.

=== Lokaler Slave-Modus ===
Im Slave-Modus können zu einem lokalen Gerät die einzelnen Sensoren als FHEM-Devices angelegt werden. Um den Slave-Modus nutzen zu können muss wie oben beschrieben ein lokales (Master-)Gerät angelegt werden. Einen Slave legt man mit <code>define <slave-name> LuftdatenInfo slave <master-name> [name-sensor1, name-sensor2]</code> an. Die Namen der Sensoren enthält man in dem man <code>get <master-name> sensors</code> ausführt. Das Ergebnis könnte eine Liste ähnlich wie diese sein:

BME680_air_quality
BME680_humidity
BME680_pressure
BME680_pressure_nn
BME680_quality_data
BME680_temperature
DHT22_humidity
DHT22_temperature
SDS011_P1
SDS011_P2
max_micro
min_micro
samples
sensor_start_date
sensor_start_time
signal

In diesem Gerät ist ein SDS011-Feinstaubsensor (vergebene Bezeichnung ''SDS011''), ein BME680-Umweltsensor (vergebene Bezeichnung ''BME680'') und ein DHT22-Luftfeuchte-/Temperatursensor (vergebene Bezeichnung ''DHT22'') verbaut.

Möchte man nun die Werte des BME680 in ein Slave-Gerät umleiten, muss man dieses wie folgt definieren:
defmod <slave-bme680> LuftdatenInfo slave <master-name> BME680_air_quality BME680_humidity BME680_pressure BME680_pressure_nn BME680_quality_data BME680_temperature

Die anderen gelisteten "Sensoren" sind keine, sondern Datenpunkte:

{| class="wikitable"
|-
! Wert !! Bedeutung
|-
| max_micro || unbekannt
|-
| min_micro || unbekannt
|-
| sensor_start_date || Datum an dem das Gerät gestartet wurde
|-
| sensor_start_time || Zeitpunkt zu dem das Gerät gestartet wurde
|-
| signal || Wifi-Leistungspegel (Signalstärke) in dBm
|}

[[Kategorie:Other Components]]

Luftdaten.info/Feinstaub

2018-12-28T17:47:15Z

ChristophMorrison:

{{Infobox Modul
|ModPurpose=Collect data from the Lufdaten.info project
|ModType=d
|ModCmdRef=LuftdatenInfo
|ModForumArea=Bastelecke
|ModFTopic=66674
|ModTechName=59_LuftdatenInfo.pm
|ModOwner=igami ({{Link2FU|4106|Forum}} / [[Benutzer:no_Legend|Wiki]])
}}
'''LuftdatenInfo''' ist ein Modul, das die Daten des Projektes [http://luftdaten.info/ luftdaten.info] in FHEM abrufbar macht.
Es können lokale oder entfernte Sensoren abgefragt werden.

== Sensor bauen ==
Der Bau eines Sensors wird auf der [http://luftdaten.info/feinstaubsensor-bauen/ Projektseite] beschrieben.
Die Kosten belaufen sich - je nach Bezugsquelle der einzelnen Bauteile und Bauform - auf ca. 30-50 €.

Zwei kurze Videos zum Aufbau und Flashen des Sensor sind u.a. auf Youtube zu finden:
* [https://youtu.be/8oLCTeCfabU Luftdaten.info Feinstaubsensor selber bauen]
* [https://youtu.be/NK3E083WayM luftdaten.info Feinstaubsensor NodeMCU flashen unter Windows]

== Datenschutz ==
In den Standard-Einstellung der Software werden die Messwerte zu der Projektseite hochgeladen und dort, nach dem man den Maintainern des Projekts eine E-Mail mit weiteren Daten hat zukommen lassen, auf einer [http://deutschland.maps.luftdaten.info/ Karte] dargestellt. Dazu sind die "letzten Schritte" auf der [https://luftdaten.info/feinstaubsensor-bauen/ Anleitungsseite] ganz unten zu befolgen.

Sollte keine Übertragung der Daten gewünscht sein, lassen sich die Geräte auch ausschließlich lokal betreiben und nicht von Fremden auslesen. Zumindest den Betreibern der Seite ist die Verknüpfung von Gerät zu Standort bekannt, ggf. lassen sich über die ermittelten Sensordaten auch genauere Standortdaten ermitteln.

== Daten nutzen ==
'''LuftdatenInfo''' unterstützt folgende drei Betriebsmodi:

=== Entfernte Abfrage ===
Mit <code>defmod <name> LuftdatenInfo remote <SensorID1> [<SensorID2> ..]</code> können - auch fremde - entfernte Geräte von luftdaten.info abgefragt werden. Angelegt werden neben den Werten für PM2.5 und PM10 auch Ortsdaten (ungefähre Latitude, ungefähre Longitude und Postleitzahl + Stadt). Weitere Sensoren eines Gerätes kann man ggf. durch Hochzählen der SensorID einbinden, z.B. liefert die SensorID 17382 Feinstaubdaten, SensorID 17383 liefert darüber hinaus auch noch Temperatur, Luftdruck und Luftfeuchte zurück. Andere Sensoren als der Feinstaubsensor werden aktuell auf luftdaten.info nicht angezeigt, müssen also erprobt werden.

=== Lokale Abfrage ===
Ein Gerät das Daten nicht an luftdaten.info oder eine der anderen Plattformen meldet, kann trotzdem lokal abgefragt werden. Dazu ist mit <code>defmod <name> LuftdatenInfo local <IP></code> das Gerät anzulegen. Es muss hier keine SensorID angegeben werden. Ohne weitere Einstellungen (<code>rawReadings</code>) liefert der Sensor hier allerdings keine Sensordaten! Diese kann man über den Slave-Modus einbinden.

=== Lokaler Slave-Modus ===
Im Slave-Modus können zu einem lokalen Gerät die einzelnen Sensoren als FHEM-Devices angelegt werden. Um den Slave-Modus nutzen zu können muss wie oben beschrieben ein lokales (Master-)Gerät angelegt werden. Einen Slave legt man mit <code>define <slave-name> LuftdatenInfo slave <master-name> [name-sensor1, name-sensor2]</code> an. Die Namen der Sensoren enthält man in dem man <code>get <master-name> sensors</code> ausführt. Das Ergebnis könnte eine Liste ähnlich wie diese sein:

BME680_air_quality
BME680_humidity
BME680_pressure
BME680_pressure_nn
BME680_quality_data
BME680_temperature
DHT22_humidity
DHT22_temperature
SDS011_P1
SDS011_P2
max_micro
min_micro
samples
sensor_start_date
sensor_start_time
signal

In diesem Gerät ist ein SDS011-Feinstaubsensor (vergebene Bezeichnung ''SDS011''), ein BME680-Umweltsensor (vergebene Bezeichnung ''BME680'') und ein DHT22-Luftfeuchte-/Temperatursensor (vergebene Bezeichnung ''DHT22'') verbaut.

Möchte man nun die Werte des BME680 in ein Slave-Gerät umleiten, muss man dieses wie folgt definieren:
defmod <slave-bme680> LuftdatenInfo slave <master-name> BME680_air_quality BME680_humidity BME680_pressure BME680_pressure_nn BME680_quality_data BME680_temperature

Die anderen gelisteten "Sensoren" sind keine, sondern Datenpunkte:

{| class="wikitable"
|-
! Wert !! Bedeutung
|-
| max_micro || unbekannt
|-
| min_micro || unbekannt
|-
| sensor_start_date || Datum an dem das Gerät gestartet wurde
|-
| sensor_start_time || Zeitpunkt zu dem das Gerät gestartet wurde
|-
| signal || Wifi-Leistungspegel (Signalstärke) in dBm
|}

[[Kategorie:Other Components]]

Luftdaten.info/Feinstaub

2018-12-28T17:46:59Z

ChristophMorrison:

{{Infobox Modul
|ModPurpose=Collect data from the Lufdaten.info project
|ModType=d
|ModCmdRef=LuftdatenInfo
|ModForumArea=Bastelecke
|ModFTopic=66674
|ModTechName=59_LuftdatenInfo.pm
|ModOwner=igami ({{Link2FU|4106|Forum}} / [[Benutzer:no_Legend|Wiki]])
}}
'''LuftdatenInfo''' ist ein Modul, das die Daten des Projektes [http://luftdaten.info/ luftdaten.info] in FHEM abrufbar macht.
Es können lokale oder entfernte Sensoren abgefragt werden.

== Sensor bauen ==
Der Bau eines Sensors wird auf der [http://luftdaten.info/feinstaubsensor-bauen/ Projektseite] beschrieben.
Die Kosten belaufen sich - je nach Bezugsquelle der einzelnen Bauteile und Bauform - auf ca. 30-50 €.

Zwei kurze Videos zum Aufbau und Flashen des Sensor sind u.a. auf Youtube zu finden:
* [https://youtu.be/8oLCTeCfabU Luftdaten.info Feinstaubsensor selber bauen]
* [https://youtu.be/NK3E083WayM luftdaten.info Feinstaubsensor NodeMCU flashen unter Windows]

== Datenschutz ==
In den Standard-Einstellung der Software werden die Messwerte zu der Projektseite hochgeladen und dort, nach dem man den Maintainern des Projekts eine E-Mail mit weiteren Daten hat zukommen lassen, auf einer [http://deutschland.maps.luftdaten.info/ Karte] dargestellt. Dazu sind die "letzten Schritte" auf der [https://luftdaten.info/feinstaubsensor-bauen/ Anleitungsseite] ganz unten zu befolgen.

Sollte keine Übertragung der Daten gewünscht sein, lassen sich die Geräte auch ausschließlich lokal betreiben und nicht von Fremden auslesen. Zumindest den Betreibern der Seite ist die Verknüpfung von Gerät zu Standort bekannt, ggf. lassen sich über die ermittelten Sensordaten auch genauere Standortdaten ermitteln.

== Daten nutzen ==
'''LuftdatenInfo''' unterstützt folgende drei Betriebsmodi:

=== Entfernte Abfrage ===
Mit <code>defmod <name> LuftdatenInfo remote <SensorID1> [<SensorID2> ..]</code> können - auch fremde - entfernte Geräte von luftdaten.info abgefragt werden. Angelegt werden neben den Werten für PM2.5 und PM10 auch Ortsdaten (ungefähre Latitude, ungefähre Longitude und Postleitzahl + Stadt). Weitere Sensoren eines Gerätes kann man ggf. durch Hochzählen der SensorID einbinden, z.B. liefert die SensorID 17382 Feinstaubdaten, SensorID 17383 liefert darüber hinaus auch noch Temperatur, Luftdruck und Luftfeuchte zurück. Andere Sensoren als der Feinstaubsensor werden aktuell auf luftdaten.info nicht angezeigt, müssen also erprobt werden.

=== Lokale Abfrage ===
Ein Gerät das Daten nicht an luftdaten.info oder eine der anderen Plattformen meldet, kann trotzdem lokal abgefragt werden. Dazu ist mit <code>defmod <name> LuftdatenInfo local <IP></code> das Gerät anzulegen. Es muss hier keine SensorID angegeben werden. Ohne weitere Einstellungen (<code>rawReadings</code>) liefert der Sensor hier allerdings keine Sensordaten! Diese kann man über den Slave-Modus einbinden.

=== Lokaler Slave-Modus ===
Im Slave-Modus können zu einem lokalen Gerät die einzelnen Sensoren als FHEM-Devices angelegt werden. Um den Slave-Modus nutzen zu können muss wie oben beschrieben ein lokales (Master-)Gerät angelegt werden. Einen Slave legt man mit <code>define <slave-name> LuftdatenInfo slave <master-name> [name-sensor1, name-sensor2]</code> an. Die Namen der Sensoren enthält man in dem man <code>get <master-name> sensors</code> ausführt. Das Ergebnis könnte eine Liste ähnlich wie diese sein:

BME680_air_quality
BME680_humidity
BME680_pressure
BME680_pressure_nn
BME680_quality_data
BME680_temperature
DHT22_humidity
DHT22_temperature
SDS011_P1
SDS011_P2
max_micro
min_micro
samples
sensor_start_date
sensor_start_time
signal

In diesem Gerät ist ein SDS011-Feinstaubsensor (vergebene Bezeichnung ''SDS011''), ein BME680-Umweltsensor (vergebene Bezeichnung ''BME680'') und ein DHT22-Luftfeuchte-/Temperatursensor (vergebene Bezeichnung ''DHT22'') verbaut.

Möchte man nun die Werte des BME680 in ein Slave-Gerät umleiten, muss man dieses wie folgt definieren:
defmod <slave-bme680> LuftdatenInfo slave <master-name> BME680_air_quality BME680_humidity BME680_pressure BME680_pressure_nn BME680_quality_data BME680_temperature

Die anderen gelisteten "Sensoren" sind keine, sondern Datenpunkte:

{| class="wikitable"
|-
! Wert !! Bedeutung
|-
| max_micro || unbekannt
|-
| min_micro || unbekannt
|-
| sensor_start_date || Datum an dem das Gerät gestartet wurde
|-
| sensor_start_time || Zeitpunkt zu dem das Gerät gestartet wurde
|-
| signal || Wifi-Leistungspegel (Signalstärke) in dBm
|}

[[Kategorie:Other Components]]

Luftdaten.info/Feinstaub

2018-12-28T17:44:52Z

ChristophMorrison:

{{Infobox Modul
|ModPurpose=Collect data from the Lufdaten.info project
|ModType=d
|ModCmdRef=LuftdatenInfo
|ModForumArea=Bastelecke
|ModFTopic=66674
|ModTechName=59_LuftdatenInfo.pm
|ModOwner=igami ({{Link2FU|4106|Forum}} / [[Benutzer:no_Legend|Wiki]])
}}

'''Dieser Artikel befindet sich noch im Aufbau.'''

'''LuftdatenInfo''' ist ein Modul, das die Daten des Projektes http://luftdaten.info/ in FHEM abrufbar macht.
Es können lokale oder entfernte Sensoren abgefragt werden.

== Sensor bauen ==
Der Bau eines Sensors wird auf der [http://luftdaten.info/feinstaubsensor-bauen/ Projektseite] beschrieben.
Die Kosten belaufen sich - je nach Bezugsquelle der einzelnen Bauteile und Bauform - auf ca. 30-50 €.

Zwei kurze Videos zum Aufbau und Flashen des Sensor sind u.a. auf Youtube zu finden:
* [https://youtu.be/8oLCTeCfabU Luftdaten.info Feinstaubsensor selber bauen]
* [https://youtu.be/NK3E083WayM luftdaten.info Feinstaubsensor NodeMCU flashen unter Windows]

== Datenschutz ==
In den Standard-Einstellung der Software werden die Messwerte zu der Projektseite hochgeladen und dort, nach dem man den Maintainern des Projekts eine E-Mail mit weiteren Daten hat zukommen lassen, auf einer [http://deutschland.maps.luftdaten.info/ Karte] dargestellt. Dazu sind die "letzten Schritte" auf der [https://luftdaten.info/feinstaubsensor-bauen/ Anleitungsseite] ganz unten zu befolgen.

Sollte keine Übertragung der Daten gewünscht sein, lassen sich die Geräte auch ausschließlich lokal betreiben und nicht von Fremden auslesen. Zumindest den Betreibern der Seite ist die Verknüpfung von Gerät zu Standort bekannt, ggf. lassen sich über die ermittelten Sensordaten auch genauere Standortdaten ermitteln.

== Daten nutzen ==
'''LuftdatenInfo''' unterstützt folgende drei Betriebsmodi:

=== Entfernte Abfrage ===
Mit <code>defmod <name> LuftdatenInfo remote <SensorID1> [<SensorID2> ..]</code> können - auch fremde - entfernte Geräte von luftdaten.info abgefragt werden. Angelegt werden neben den Werten für PM2.5 und PM10 auch Ortsdaten (ungefähre Latitude, ungefähre Longitude und Postleitzahl + Stadt). Weitere Sensoren eines Gerätes kann man ggf. durch Hochzählen der SensorID einbinden, z.B. liefert die SensorID 17382 Feinstaubdaten, SensorID 17383 liefert darüber hinaus auch noch Temperatur, Luftdruck und Luftfeuchte zurück. Andere Sensoren als der Feinstaubsensor werden aktuell auf luftdaten.info nicht angezeigt, müssen also erprobt werden.

=== Lokale Abfrage ===
Ein Gerät das Daten nicht an luftdaten.info oder eine der anderen Plattformen meldet, kann trotzdem lokal abgefragt werden. Dazu ist mit <code>defmod <name> LuftdatenInfo local <IP></code> das Gerät anzulegen. Es muss hier keine SensorID angegeben werden. Ohne weitere Einstellungen (<code>rawReadings</code>) liefert der Sensor hier allerdings keine Sensordaten! Diese kann man über den Slave-Modus einbinden.

=== Lokaler Slave-Modus ===
Im Slave-Modus können zu einem lokalen Gerät die einzelnen Sensoren als FHEM-Devices angelegt werden. Um den Slave-Modus nutzen zu können muss wie oben beschrieben ein lokales (Master-)Gerät angelegt werden. Einen Slave legt man mit <code>define <slave-name> LuftdatenInfo slave <master-name> [name-sensor1, name-sensor2]</code> an. Die Namen der Sensoren enthält man in dem man <code>get <master-name> sensors</code> ausführt. Das Ergebnis könnte eine Liste ähnlich wie diese sein:

BME680_air_quality
BME680_humidity
BME680_pressure
BME680_pressure_nn
BME680_quality_data
BME680_temperature
DHT22_humidity
DHT22_temperature
SDS011_P1
SDS011_P2
max_micro
min_micro
samples
sensor_start_date
sensor_start_time
signal

In diesem Gerät ist ein SDS011-Feinstaubsensor (vergebene Bezeichnung ''SDS011''), ein BME680-Umweltsensor (vergebene Bezeichnung ''BME680'') und ein DHT22-Luftfeuchte-/Temperatursensor (vergebene Bezeichnung ''DHT22'') verbaut.

Möchte man nun die Werte des BME680 in ein Slave-Gerät umleiten, muss man dieses wie folgt definieren:
defmod <slave-bme680> LuftdatenInfo slave <master-name> BME680_air_quality BME680_humidity BME680_pressure BME680_pressure_nn BME680_quality_data BME680_temperature

Die anderen gelisteten "Sensoren" sind keine, sondern Datenpunkte:

{| class="wikitable"
|-
! Wert !! Bedeutung
|-
| max_micro || unbekannt
|-
| min_micro || unbekannt
|-
| sensor_start_date || Datum an dem das Gerät gestartet wurde
|-
| sensor_start_time || Zeitpunkt zu dem das Gerät gestartet wurde
|-
| signal || Wifi-Leistungspegel (Signalstärke) in dBm
|}

[[Kategorie:Other Components]]

Energiesparende Schimmelbekämpfung / Luftentfeuchtung in kritischen Räumen

2018-12-14T17:49:57Z

ChristophMorrison: /* Alles zusammenpacken */ Link gefixt

==Voraussetzungen / Benötigte Technik==
* Einen Raum mit kalten Wandstellen
* Innentemperatursensor und Luftfeuchtesensor im betroffenen Raum (z.B. [[HomeMatic]] [[HM-CC-RT-DN Funk-Heizkörperthermostat|Wandthermostat]])
* Außentemperatursensor (oder notfalls die aktuellen Wetterdaten von Yahoo und Co.)
* Infrarotthermometer (ohne Anbindung an FHEM und nur leihweise für ein paar Tage, wird nur zum Einrichten benötigt)
* Luftentfeuchter, der sich z.B. per HomeMatic-Zwischenstecker an/ausschalten lässt (optional, man kann sich natürlich auch nur Warnungen ausgeben lassen)

==Ausgangslage==
Schimmel will trinken, um Wachsen zu können. Möchte man einschätzen, ob in einem Raum Schimmelgefahr besteht, kann man das mit FHEM-Bordmitteln über das Taupunkt-Modul [[dewpoint]] machen. Wenn der Taupunkt der Raumluft über der Oberflächentemperatur der Wand liegt, dann kondensiert das Wasser und es schimmelt. Man muss also nur die Taupunkttemperatur Td(Raumtemperatur, rel. Raumluftfeuchte) mit der Wandtemperatur vergleichen. Hierzu muss man natürlich die Wandtemperatur (an der kältesten Stelle, hier kondensiert das Wasser aus der Luft zuerst) ersteinmal kennen. Das Problem haben wir aber immer, egal wie wir es anstellen - dazu später mehr.

Diese Variante per Taupunkt ist aber nur die halbe Miete: Laut verschiedenen Quellen wächst mancher Schimmelpilz schon viel früher - ohne kondensierten, flüssigen Wasserfilm, allein durch eine hohe relative Luftfeuchte von über 70% (manche Quellen sagen 80%). Hat eine Oberfläche genau die Taupunkttemperatur der Raumluft, ist die relative Luftfeuchte dort bei 100% - also deutlich über den gefährlichen 70-80%, so dass sich Schimmel dort schon recht wohlfühlen sollte.

Nun könnte man entweder ein paar Grad "Sicherheitsmarge" auf den Taupunkt addieren. Prima. Nur wie groß sollte unsere Sicherheitsmarge genau sein, ohne den Raum mit z.B. 200-300 Watt sehr energieintensiv zu viel zu entfeuchten? Dann vielleicht doch ganz simpel ansetzen und in FHEM definieren: Schimmelwarnung ausgeben oder Luftentfeuchter anschalten bei über 70% Raumluftfeuchte. Punkt. Dazu könnte man dann bequem z.B. einen Homematic-Raumthermostaten nehmen und dessen Sensorwert für die Luftfeuchtigkeit auf Überschreitung der 70%-Marke prüfen - so tun das sicher auch viele. Aber das kann wie in meinem Fall - die Wände sind an einigen Stellen kälter als die Raumluft - genau wie die Taupunkt-Methode jämmerlich schiefgehen.

Das Problem dabei ist nämlich, dass die Luft nicht einfach schlagartig an Flächen auskondensiert, die kälter sind als der Taupunkt. Die relative Luftfeuchte steigt mit jedem Grad weniger kontinuierlich an. Und dieser Effekt ist je nach Bausubstanz und "Wandkälte" durchaus erheblich. So ist die 70%-Marke an der Wand schon mitunter bei einer Luftfeuchtigkeit im Raum von 55% oder gar weniger überschritten. Eine „Sicherheitsmarge“ muss dann schon ganz schön groß ausfallen - und der Raum z.B. dauerhaft auf 50% entfeuchtet werden. Oh je, die Stromrechnung, denn das ist an wärmeren Tagen, wo die Wände vielleicht nur 2 Grad kälter sind als die Luft im Raum, viel zu viel. Bei mir liegt z.B. in den Fensterzargen die (mit einem Infrarotthermometer gemessene) Oberflächentemperatur an kalten Tagen mit Temperaturen unter dem Gefrierpunkt manchmal 10 Grad unter der Raumtemperatur - man spricht bei solchen nicht immer behebbaren Baumängeln von sog. „Kältebrücken“. Das wirkt sich an solchen Tagen schon extrem auf die relative Luftfeuchte aus und ließ bei mir den Schimmel wachsen.

Nur wie stark ist diese Auswirkung denn nun genau? Das hängt wie gesagt von der Differenz zwischen Raumtemperatur und Wandtemperatur (und damit der Außentemperatur) ab - je größer die Differenz, desto stärker der Feuchteanstieg in Wandnähe. Leider ist der Zusammenhang aber nicht linear, so dass man das ausrechnen muss. Da ich das nirgends fertig gefunden habe, habe ich [http://www.wetterochs.de/wetter/feuchte.html hier] die nötigen Formeln gefunden, umgestellt und in folgende Funktion für die 99_myUtils.pm gegossen:

sub shiftRelHumidity($$$)
# Uses a pair of relative humidity and temperature ($r1, $T1) to calculate the relative
# humidity on spots with same absolute humidity of the air but different temperature $T2.
#
# Useful to calculate the relative humidity near the surface of cold walls. Therefore, use the rel.
# humidity of the room ($r1 in percent), the room Temperature ($T2 in degrees of C) and the temperature
# of the surface of the wall ($T2 in degrees of C). Returns the rel. humidity on the surface in pct then.
{
my ($T1, $r1, $T2) = @_;
my $r2 = ($r1 * 10**((7.62*$T1)/(234.175+$T1))*(273.15+$T2)) / ( 10**((7.62*$T2)/(234.175+$T2))*(273.15+$T1));
return $r2;
}

Wen die Herleitung interessiert und wer nachrechnen möchte, ob ich mich vertan habe, der möge es mich wissen lassen. Einem Vergleich mit der Berechnung [http://wetterstationwien22.at/html/relative-luftfeuchte--erwarmung-.html dieser Seite] hält die Formel aber einigermaßen Stand.

Wir können hiermit nun also in Abhängigkeit von der Raumtemperatur, der relativen Luftfeuchte des Raumes und der Oberflächentemperatur der Wand die relative Luftfeuchte in Wandnähe ziemlich genau ausrechnen. Und dann das Ganze in ein UserReading packen und unseren Luftentfeuchter danach regeln - oder unsere Schimmelwarnung versenden, mit dem Hinweis, dass vielleicht mal gelüftet oder der Raum mehr beheizt werden müsste (beides kann helfen - das ist aber ein anderes Thema und will ich hier nicht weiter behandeln). Da gibt es vorher aber nach wie vor noch ein mittelprächtiges Problem: woher nehmen wir die Wandtemperatur?

==Wandtemperatur ermitteln==
Perfekt wäre natürlich, einen Oberflächentemperatursensor an der kältesten Stelle der Wand zu platzieren und den Wert direkt zu messen. Wer es ganz genau machen will und seinen Luftentfeuchter wirklich sparsam einsetzen will, der sollte das vielleicht auch so tun - dann kann man aber dort auch gleich die Luftfeuchtigkeit oder Oberflächenfeuchtigkeit messen. Meistens ist das aber relativ umständlich, unhübsch und kostet auch noch Geld für zusätzliche Sensoren.

Was sich bei mir aber auch als ziemlich genau herausgestellt hat, ist, die Wandtemperatur kontinuierlich zu schätzen - und zwar in Abhängigkeit von Innen- und Außentemperatur. Hierzu ist es nötig, eine kleine Messreihe mit einem Infrarotthermometer zu machen: Gemessen wird hiermit die Oberflächentemperatur der Wand an der kältesten Stelle, die sich im Raum finden lässt - also z.B. in der Fensterzarge. Zusätzlich benötigen wir die Innentemperatur des Raumes und die Außentemperatur, die FHEM zu dieser Zeit gemessen hat - die kann man ja nach der Messung im FileLog / [[DbLog]] nachschauen.

Aus diesen 3 Werten berechnen wir uns einen "Isolationsfaktor" K:

K = (Oberflächentemperatur - Außentemperatur) / (Innentemperatur - Außentemperatur)

Wichtig ist es, die Messung durchzuführen, wenn es draußen richtig schön kalt ist (spät abends / nachts bei Minusgraden) und die Raumtemperatur längere Zeit konstant war - direkt nach dem Aufheizen des Bades bei 15 Grad Außentemperatur ergibt das Ganze also eher keine genauen Werte. Die Außentemperatur sollte idealerweise auch konstant sein, aber das ist sie nunmal nicht, daher kann das Ganze nicht perfekt funktionieren - aber für unsere Zwecke durchaus ausreichend. Die Messung solltet ihr aber auf jeden Fall ein paar mal wiederholen (6-7 mal zu verschiedenen Zeiten, am besten an mehreren Tagen), ggf. Ausreißer aussortieren und dann K mitteln. Sollte K bei euch nicht sonderlich konstant sein - was je nach Bausubstanz / Beheizung durchaus möglich ist - nehmt tendentiell eher einen kleineren Wert, geht also von schlechterer Dämmung aus, wenn ihr sicher sein wollt, dass es nicht schimmelt. Bei mir ergaben sich für meine Altbauwohnung Werte zwischen 0,67 und 0,70 - Mittelwert ist 0,68, den verwende ich seitdem.

Über den Wert können wir nun mit folgender Funktion für die 99_myUtils.pm künftig die Wandtemperatur jederzeit aus Innen- und Außentemperatur schätzen:

sub wallSurfaceTemp($$$)
# Estimates the temperature of the inner wall surface given the outside Temperature in degrees of C as $Tinside,
# the outdoor-temperature $Toutside in degrees of C and an insulation Factor $Kinsulation with K = 1 (theoretical perfect insulation, e.g. vacuum) and
# K = 0 (no insulation at all, means: less than a sheet of paper). You have to calculate K on your own by measuring inside-, outside-, and wall-temperature,
# preferably by averaging multiple measurements on cold days with constant heating of the room.
{
my ($Tinside, $Toutside, $Kinsulation) = @_;
my $Tsurface = ($Tinside * $Kinsulation) + ($Toutside * (1 - $Kinsulation));
return $Tsurface;
}

Wirklich genau ist die Methode wie gesagt nicht und unterliegt gewissen Schwankungen. Sie ist inspiriert durch [http://www.u-wert.net/u-wert-messen/ diesen Artikel] (und auf das für uns nötigste weiter vereinfacht). Dort sind auch die prinzipiellen Nachteile dieser Schätzung diskutiert worden. Ich habe meine Messreihe vor knapp einem Jahr durchgeführt und immer mal wieder das Ergebnis mit der realen Wandtemperatur verglichen: die Abweichung lag maximal bei 1,5 Grad, normalerweise stimmte sie aber auf +/- 0,5 Grad genau. Damit kann ich gut leben ;-) Möglicherweise funktioniert das bei euch nicht so gut - einfach testen.

==Alles zusammenpacken==
Die zwei neuen Werte (Wandtemperatur und „Wandfeuchte“ - bessergesagt, relative Luftfeuchte in Wandnähe) können wir nun z.B. in die UserReadings unseres Wandthermostaten packen. Hier mal ein Beispiel zum kopieren in das Feld für das UserReadings-Attribut:

wandTemp { sprintf("%.1f", wallSurfaceTemp(ReadingsVal("kuechenthermometer","temperature",15),ReadingsVal("aussenthermometer","temperature",0),0.68)) }, \
wandHumidity { sprintf("%.1f", shiftRelHumidity( ReadingsVal("kuechenthermometer","temperature",17), ReadingsVal("kuechenthermometer","humidity",90), \
wallSurfaceTemp( ReadingsVal("kuechenthermometer","temperature",15), ReadingsVal("aussenthermometer","temperature",0), 0.68) ) ) }

Nicht vergessen, die 0.68 durch euren ermittelten K-wert zu ersetzen und event-on-change-reading anzupassen falls gesetzt, so dass ihr auch Events für die Userreadings bekommt.

Nun könnt ihr beide Werte ganz normal in Plots einfügen, euch Warnungen bei wandHumidity > 70% oder 80% schicken lassen oder das ganze auch per DOIF zur Entfeuchterregelung benutzen:

define di_bad.oben.luftentfeuchter \
DOIF ([bad.oben.thermometer:wandHumidity] > 68 and [bad.oben.fenster] eq "geschlossen") (set bad.oben.luftentfeuchter_Sw on) \
DOELSEIF ([bad.oben.thermometer:wandHumidity] < 60) (set bad.oben.luftentfeuchter_Sw off) \
DOELSEIF ([bad.oben.fenster] eq "offen") (set bad.oben.luftentfeuchter_Sw off)

Hier regele ich einen Luftentfeuchter an einem [[HM-ES-PMSw1-Pl Funk-Schaltaktor 1-fach mit Leistungsmessung|HomeMatic Zwischenstecker mit Leistungsmessung]] genau so, dass die Wand immer unter 70% bleibt (mit 2% Sicherheitsmarge). Und beim Lüften geht das Ding sofort aus. Ihr müsst dann nur noch einen Luftentfeuchter finden, der diese Art des Ein-/Ausschaltens per Steckerziehen mitmacht und ein wenig mit der Hysterese (dem Abschaltpunkt - hier 60%) spielen, so dass es in euren Raum passt. Ich verwende übrigens einen comfee MDF2-16DEN3 - ein sehr preiswerter Luftentfeuchter, der nicht wie viele andere die Eigenart hat, nach Stromwiederkehr einfach auszubleiben. Er genehmigt seinem Kompressor danach zwar eine kurze Zwangspause, läuft dann aber wieder an.

== Links ==
* {{Link2Forum|Topic=29773|LinkText=Forenthread zu diesem Thema}}

[[Kategorie:HOWTOS]]