DevelopmentModuleAPI: Unterschied zwischen den Versionen
Justme (Diskussion | Beiträge) |
Justme (Diskussion | Beiträge) |
||
Zeile 195: | Zeile 195: | ||
}; | }; | ||
</source> | </source> | ||
=== asyncOutput === | |||
:<source lang="perl">asyncOutput($cl, $txt);</source> | |||
TODO | |||
Parameter: | |||
{| class="wikitable" | |||
|- | |||
! Parameter!! Bedeutung | |||
|- | |||
| style="vertical-align:top" | '''<code>$cl</code>''' | |||
''mandatory'' | |||
|| Die Hash-Referenz desjenigen Kanals (telnet oder FhemWeb instanz) auf das die Ausgabe erfolgen soll. Wird in $hash->{CL} an die SetFn und GetFn übergeben. | |||
|- | |||
| style="vertical-align:top" | '''<code>$txt</code>''' | |||
''mandatory'' | |||
|| Der Text der ausgegeben werden soll. | |||
|} | |||
== Time / Timestamp == | == Time / Timestamp == |
Version vom 26. Mai 2016, 18:00 Uhr
Please note: This list of functions is not official maintained by the 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 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 identifiziern zu können
Natürlich hat diese Seite keinen Anspruch auf Vollständigkeit und jeder ist aufgefordert mitzuarbeiten, sobald er beim Stöbern über einen Funktion stolpert, die auch andere interessieren könnte.
FHEM-Befehlsausführung
AnalyzeCommand
AnalyzeCommand ermöglicht das Parsen und die Ausführung eines FHEM-Befehls, wie in FHEMWEB im Kommandoeingabefeld enthalten.
$error = AnalyzeCommand($client_hash, $cmd)
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Der Definition-Hash, welcher für die Ausführung dieses Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition das Kommando $cmd ausführen darf (Vorgangs-Typ: cmd ). Der Definition-Hash muss in SNAME den zum Attribut validFor (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert undef übergeben wird, erfolgt keine Prüfung.
|
$cmd
mandatory |
Kommandos, die ausgeführt werden sollen. Beispiel:
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$error
|
Fehlermeldungen, die beim ausführen des Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird undef 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.
$errors = AnalyzeCommandChain ($client_hash, $cmds)
Parameter:
Parameter | Bedeutung |
---|---|
$client_hash
mandatory |
Der Definition-Hash, welcher für die Ausführung dieser Kommandos verantwortlich ist. Dies dient zur Prüfung, ob diese Definition die Kommandos $cmds ausführen darf (Vorgangs-Typ: cmd ).Der Definition-Hash muss in SNAME den zum Attribut validFor (im zugehörigen allowed-Device) passenden Devicenamen tragen, damit die Prüfung durchgeführt wird. Wenn anstatt eines Definitions-Hashes der Wert undef übergeben wird, erfolgt keine Prüfung.
|
$cmds
mandatory |
Kommandokette, welche ausgeführt werden soll, durch ; getrennt.Beispiel:
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$errors
|
Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird undef zurückgegeben.
|
EvalSpecials
$final_cmd = EvalSpecials($cmd, %specials)
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 %specials
in $cmd
gesucht und durch die entsprechenden Werte aus %specials
ersetzt.
Diese Funktion hat je nach gewähltem Featurelevel (globales Attribut featurelevel
) 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:
Parameter | Bedeutung |
---|---|
$cmd
mandatory |
Eine gültige FHEM-Kommando-Kette welche mit etwaigen Platzhaltern versehen ist, die ersetzt werden sollen.
Bsp: |
%specials
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 (_ ) bestehen. Generell sollten die Schlüssel aber nur aus Großbuchstaben bestehen.
Bspw: |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$final_cmd
|
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
my($a, $h) = parseParams($cmd, $separator);
parseParams() ermöglicht das Parsen von Kommandozeilenargumenten und lässt sich z.b. für die Parameter von define (DefFn), get (GetFn) und set (SetFn) verwenden. Beim Parsen werden erkannt:
- einfache durch den Separator getrennte Zeichenfolgen
- benannte Parameter der Form
<name>=<wert>
- Werte können in einfache (
'
) oder doppelte ("
) 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.
- Werte können in einfache (
- in
{...}
eingeschlossener Perlcode. Hier wird nach der ersten öffnenden bis zur zugehörigen schliessenden Klammer gesucht. D.h. bis die gleichen Anzahl öffnender und schliessender Klammern erreicht ist.
In der Modul X_Initialize
routine lässt sich mit $hash->{parseParams} = 1;
festlegen das parseParams für die define, get und set Argumente automatisch aufgerufen und das Ergebniss an die DefFn, GetFn und SetFn übergeben wird.
Parameter:
Parameter | Bedeutung |
---|---|
$cmd
mandatory |
Die Argumente des Kommandos als String oder als ArrayRef. |
$separator
optional |
Der Separater an dem die Parameterzeile gesplittet werden soll.
Standardwert: ' ' |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$a
|
Eine Ref auf ein Array das alle nicht benannten Parameter in der Reihenfolge ihres vorkommen enthält. |
$h
|
Eine Ref auf einen Hash der die Werte aller benannten Parameter mit ihrem Namen als Key enthält. |
Beispiel: Die Zeile
set <name> test1 test2=abc test3 "test4 test4" test5="test5 test5" test6='test6=test6' test7= test8="'" test9='"' {my $x = "abc"} test10={ { my $abc ="xyz" } }';
wird in die folgenden Elemente geparsed:
#Die nicht benannten Paramter:
$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'
};
asyncOutput
asyncOutput($cl, $txt);
TODO
Parameter:
Parameter | Bedeutung |
---|---|
$cl
mandatory |
Die Hash-Referenz desjenigen Kanals (telnet oder FhemWeb instanz) auf das die Ausgabe erfolgen soll. Wird in $hash->{CL} an die SetFn und GetFn übergeben. |
$txt
mandatory |
Der Text der ausgegeben werden soll. |
Time / Timestamp
FmtDateTimeRFC1123
$timestampGMT = FmtDateTimeRFC1123($timestamp)
Gibt den übergebenen UNIX-Timestamp (Sekunden seit EPOCH-Beginn) formatiert nach RFC 1123 zurück.
Parameter:
Parameter | Bedeutung |
---|---|
$timestamp
mandatory |
Zeitangabe wie sie von der time() Funktion zurückgegeben wirdBsp: |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestampGMT
|
Zeitstempel GMT (Greenwich Mean Time) wie er in RFC 1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet.
|
FmtDateTime
$timestamp = FmtDateTime($time)
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:
Parameter | Bedeutung |
---|---|
$time
mandatory |
Zeitangabe wie sie von der time() Funktion zurückgegeben wird.Bsp: |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel in lokaler Zeitzone im Format
|
TimeNow
$timestamp = TimeNow()
Die Funktion TimeNow() gibt die aktuelle lokale Zeit als formatierte Zeichenkette zurück. Diese Funktion hat keine Übergabeparameter.
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format
Benutzt die Funktion |
fhemTimeGm
$timestamp = fhemTimeGm($sec, $min, $hour, $mday, $month, $year)
Wandelt einen Zeitpunkt als Greenwich Mean Time (GMT) basierend auf den einzelnen Datumsangaben, wie er bspw. durch die Perl-Funktion gmtime()
erzeugt wird, in einen UNIX-Timestamp um.
Parameter:
Parameter | Bedeutung |
---|---|
$sec
mandatory |
Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. |
$min
mandatory |
Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. |
$hour
mandatory |
Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. |
$mday
mandatory |
Die Tag-Komponente als Ganzzahl zwischen 1 und 31. |
$month
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. |
$year
mandatory |
Die Jahres-Komponente. Das Jahr wird dabei als nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116. |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) Bsp: |
fhemTimeLocal
$timestamp = fhemTimeLocal($sec, $min, $hour, $mday, $month, $year)
Wandelt einen Zeitpunkt in lokaler Zeit basierend auf den einzelnen Datumsangaben wie er bspw. durch die Perl-Funktion localtime()
erzeugt wird in einen UNIX-Timestamp um.
Parameter:
Parameter | Bedeutung |
---|---|
$sec
mandatory |
Die Sekunden-Komponente als Ganzzahl zwischen 0 und 59. |
$min
mandatory |
Die Minuten-Komponente als Ganzzahl zwischen 0 und 59. |
$hour
mandatory |
Die Stunden-Komponente als Ganzzahl zwischen 0 und 23. |
$mday
mandatory |
Die Tag-Komponente als Ganzzahl zwischen 1 und 31. |
$month
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. |
$year
mandatory |
Die Jahres-Komponente. Das Jahr wird dabei als nicht als komplette Jahreszahl angegeben, sondern als Differenz seit dem Jahr 1900. Das Jahr 2016 entspricht demnach dem Wert 116. |
Rückgabewerte:
Rückgabe | Bedeutung |
---|---|
$timestamp
|
Zeitstempel als UNIX-Timestamp (Sekunden seit EPOCH-Beginn) Bsp: |
Erzeugen von Readings / Events
readingsBeginUpdate
readingsBeginUpdate($hash)
Die Funktion readingsBeginUpdate() bereitet die Definition mit dem Hash $hash
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:
Parameter | Bedeutung |
---|---|
$hash |
Die Hash-Referenz der Definition wo Readings geupdatet werden sollen |
readingsBulkUpdate
$rv = readingsBulkUpdate($hash, $reading, $value);
$rv = readingsBulkUpdate($hash, $reading, $value, $changed);
Die Funktion readingsBulkUpdate() führt ein Update eines einzelnen Readings für die Definition $hash
durch. Dabei wird das Readings $reading
auf den Wert $value
gesetzt. Bevor diese Funktion benutzt werden kann, muss readingsBeginUpdate() zuvor aufgerufen werden, ansonsten werden keine Updates durchgeführt.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo Readings geupdatet werden sollen |
$reading
mandatory |
Name des Readings, welches geupdatet werden soll |
$value
mandatory |
Der Wert, welchen das Reading annehmen soll |
$changed
optional |
Flag, ob ein Event für dieses Update erzeugt werden soll (Wert: 1 ). Oder ob definitiv kein Event erzeugt werden soll (Wert: 0 ). Wenn nicht gesetzt, wird aufgrund entsprechender Attribute in der Definition von $hash entschieden, ob ein Event zu erzeugen ist, oder nicht (Attribute: event-on-change-reading, event-on-update-reading, event-min-interval, ...)
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$rv |
Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. |
readingsEndUpdate
readingsEndUpdate($hash, $do_trigger);
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 $hash
. Desweiteren werden nachgelagerte Tasks wie bspw. die Erzeugung von User-Readings (Attribut: userReadings
), sowie die Erzeugung des STATE aufgrund des Attributs stateFormat
durchgeführt. Sofern $do_trigger
gesetzt ist, werden alle anstehenden Events nach Abschluss getriggert.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo Readings geupdatet wurden. |
$do_trigger
mandatory |
Flag, ob entsprechende Events der einzelnen Readings getriggert werden sollen (Wert: 1 ). Wenn dieses Flag den Wert 0 oder undef besitzt, werden keine Events für alle Readings die seit dem Aufruf von readingsBeginUpdate() mittels readingsBulkUpdate() gesetzt wurden, erzeugt.
|
readingsSingleUpdate
$rv = readingsSingleUpdate($hash, $reading, $value, $do_trigger);
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:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition, wo das Reading geupdatet werden soll |
$reading
mandatory |
Name des Readings, welches geupdatet werden soll |
$value
mandatory |
Der Wert, welchen das Reading annehmen soll |
$do_trigger
mandatory |
Flag, ob evtl. ein Event für das Reading getriggert werden soll (Wert: 1 , Event ist abhängig von den Attributen: event-on-change-reading, event-on-update-reading, event-min-interval, ...). Wenn dieses Flag den Wert 0 oder undef besitzt, wird kein Event erzeugt.
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$rv |
Zeichenkette bestehend aus Reading und Wert getrennt durch einen Doppelpunkt, welcher anzeigt, auf welchen Wert das Reading tatsächlich gesetzt wurde. |
DoTrigger
$ret = DoTrigger($name, $new_state);
$ret = DoTrigger($name, $new_state, $no_replace);
Die Funktion DoTrigger() triggert alle angesammelten Events in $hash->{CHANGED}
sowie zusätzlich das Event $new_state
für die Definition $name
und führt alle verarbeitenden Aktionen in allen Empfängern zu diesem Event aus. Wenn in $hash->{CHANGED}
keine zu bearbeitenden Änderungen enthalten sind, wird lediglich $new_state
getriggert (sofern gesetzt).
Diese Funktion wird implizit in der Funktion readingsEndUpdate() aufgerufen und muss daher nicht nochmal aufgerufen werden.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Name der Definition deren Events durchgeführt werden sollen. |
$new_state
mandatory |
Das Event welches zusätzlich zu bereits anstehenden Events aus $hash->{CHANGED} getriggert werden soll. Wenn dieser Wert undef ist, werden nur alle Events aus $hash->{CHANGED} bearbeitet, sofern $hash->{CHANGED} gefüllt ist.
|
$no_replace
optional |
Optionales Flag, welches die Ersetzung von Events durch das Attribut eventMap verhindert (Wert: 1 ).
|
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$ret |
Zeichenkette welche alle Return-Werte aller aufgerufenen Notify-Funktionen beinhaltet, sofern diese einen Fehler melden. Diese Meldung wird parallel im FHEM-Logfile ausgegeben. |
Timer
InternalTimer
InternalTimer($timestamp, $functionName, $args);
InternalTimer($timestamp, $functionName, $args, $waitIfInitNotDone)
Die Funktion InternalTimer() ermöglicht das verzögerte Ausführen von einer bestimmten Funktion zu einem späteren Zeitpunkt. Die übergebene Funktion $functionName
wird dabei zum Zeitpunkt $timestamp
mit dem Parameter $arg
ausgeführt.
Parameter:
Parameter | Bedeutung |
---|---|
$timestamp
mandatory |
Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: gettimeofday() + 30 um in 30 Sekunden etwas zu starten)
|
$functionName
mandatory |
Der Name der Funktion welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus") |
$arg
mandatory |
Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash. |
$waitIfInitNotDone
optional |
VORSICHT! NUR BENUTZEN WENN MAN ES WIRKLICH BENÖTIGT. Wenn dieser Wert auf 1 ist und die Funktion ausgeführt wird, während FHEM startet ($init_done == 0), dann wird InternalTimer direkt solange warten bis der angegebene Zeitpunkt erreicht ist, UND DIE FUNKION DIREKT AUSFÜHREN. Das bedeutet, dass InternalTimer() dann solange läuft, bis der Zeitpunkt erreicht ist und die angegebene Funktion ausgeführt wurde.
Standardwert: 0 |
RemoveInternalTimer
RemoveInternalTimer($arg);
RemoveInternalTimer($arg, $function);
Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter $arg
gescheduled sind. Optional kann man zusätzlich die Suche auf eine bestimmte Funktion $function
weiter einschränken.
Parameter:
Parameter | Bedeutung |
---|---|
$arg
mandatory |
Der Übergabeparameter nach wem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht. |
$function
optional |
Der Funktionsname der zusätzlich zu $arg gesucht werden soll.
|
SetExtensionsCancel
SetExtensionsCancel($hash);
Die Funktion SetExtensionsCancel löscht den möglicherweise noch anstehenden Timer der durch ein on-for-timer oder off-for-timer über die SetExtensions angelegt wurde. Sollte in der SetFn aufgerufen werden bevor der Devicezustand durch ein anderes Kommando geändert wird.
Parameter:
Parameter | Bedeutung |
---|---|
$hash
mandatory |
Die Hash-Referenz der Definition durch die der Timer angelegt wurde. |
Definitionen suchen
devspec2array
@list = devspec2array($devspec);
@list = devspec2array($devspec, $client_hash)
Die Funktion devspec2array() gibt eine Array mit Definitionsnamen zurück die auf die übergebene Device-Specification $devspec
matchen.
Sollte keine Definition auf die übergebene Spezifikation passen, so wird $devspec
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 %defs
zu prüfen.
Die genaue Syntax einer Device-Specification ist in der commandref erläutert. Die Funktion devspec2array() setzt diese Syntax um und gibt die gefundenen Definitions-Namen zurück.
Parameter:
Parameter | Bedeutung |
---|---|
$devspec
mandatory |
Die Device-Specification zum suchen nach Definitions-Namen. |
$client_hash
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: devicename ).
|
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
@list |
Array mit einer Liste aller Definitions-Namen die zu der übergebenen Device-Specification passen. Sofern keine Definition auf die Spezifikation passt wird $devspec unverändert zurückgegeben. Wenn $client_hash gesetzt ist und die Definition diesen Vorgang nicht ausführen darf, wird "" (Leerstring) zurückgegeben.
|
Daten abfragen/auslesen
ReadingsVal
$value = ReadingsVal($name, $reading, $default)
Die Funktion ReadingsVal() gibt den inhaltlichen Wert des Readings $reading
der Definition $name
zurück. Sollte das gewünschte Reading nicht existieren, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings welcher ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Inhalt des gewünschten Readings oder $default , wenn es nicht existiert.
|
ReadingsTimestamp
$timestamp = ReadingsTimestamp($name, $reading, $default)
Die Funktion ReadingsTimestamp() gibt den Zeitstempel des Readings $reading
der Definition $name
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 $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem der Zeitstempel für das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings für welches der Zeitstempel ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$timestamp |
Zeitstempel des gewünschten Readings in lokaler Zeitzone im Format
|
ReadingsAge
$seconds = ReadingsAge($name, $reading, $default)
Die Funktion ReadingsAge() gibt die Dauer in Sekunden seit der letzten Aktualisierung des Readings $reading
der Definition $name
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 $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem die Dauer der letzten Aktualisierung für das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings für welches die Dauer der letzten Aktualisierung ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$seconds |
Die Sekunden als Ganzzahl, welche seit der letzten Aktualisierung vergangen sind |
ReadingsNum
$number = ReadingsNum($name, $reading, $default)
Die Funktion ReadingsNum() extrahiert einen numerischen Wert aus dem Reading $reading
der Definition $name
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 $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll. |
$reading
mandatory |
Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$number |
Numerischer Wert des gewünschten Readings oder $default , wenn es nicht existiert.
|
AttrVal
$value = AttrVal($name, $attribute, $default)
Die Funktion AttrVal() gibt den aktuell konfigurierten Inhalt des Attribut $attribute
der Definition $name
zurück. Sollte das gewünschte Attribut nicht existieren bzw. nicht gesetzt sein, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem das gewünschte Attribut ausgelesen werden soll. |
$attribute
mandatory |
Der Name des Attributs, dessen Wert ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Attribut nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Inhalt des gewünschten Attributs oder $default , wenn es nicht existiert.
|
InternalVal
$value = InternalVal($name, $internal, $default)
Die Funktion InternalVal() gibt den aktuellen Inhalt eines Internals $internal
der Definition $name
zurück. Sollte das gewünschte Internal nicht existieren bzw. nicht gesetzt sein, wird $default
zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem das gewünschte Internal ausgelesen werden soll. |
$internal
mandatory |
Der Name des Internals, dessen Wert ausgelesen werden soll. |
$default
mandatory |
Der Standardwert der zurückgegeben werden soll, sofern das Internal nicht existiert. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Inhalt des gewünschten Internal oder $default , wenn es nicht existiert.
|
Value
$value = Value($name)
Die Funktion Value() gibt den aktuellen Status Definition $name
zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird ""
(Leerstring) zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem der Status ausgelesen werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
Status der gewünschten Definition |
OldValue
$value = OldValue($name)
Die Funktion OldValue() gibt den Status der Definition $name
zurück BEVOR der aktuelle Status aufgrund eines Events gesetzt wurde. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird ""
(Leerstring) zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem der Status ausgelesen werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$value |
vorherige Status der gewünschten Definition |
OldTimestamp
$timestamp = OldTimestamp($name)
Die Funktion OldTimestamp() gibt den Zeitpunkt der letzten Statusänderung der Definition $name
als Zeichenkette zurück. Sollte die gewünschte Definition nicht existieren bzw. nicht gesetzt sein, wird ""
(Leerstring) zurückgegeben.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Namen aus dem der Status ausgelesen werden soll. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$timestamp |
Zeitstempel in lokaler Zeitzone im Format
|
Attribute in anderen Definitionen bereitstellen
addToAttrList
addToAttrList($attrib)
Die Funktion addToAttrList() fügt das Attribut mit dem Namen $attrib
zu dem Attribut userattr
der Definition global
hinzu. Damit kann dieses Attribut in allen systemweiten Definitionen verwendet und gesetzt werden.
Parameter:
Parameter | Bedeutung |
---|---|
$attrib
mandatory |
Der Name des Attributs, welches für alle Definitionen verfügbar gemacht werden soll. |
addToDevAttrList
addToDevAttrList($name, $attrib)
Die Funktion addToDevAttrList() fügt das Attribut mit dem Namen $attrib
zu dem Attribut userattr
der Definition $name
hinzu. Damit kann dieses Attribut in der Definition $name
verwendet und gesetzt werden.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Name der Definition, für welche das Attribut verfügbar gemacht werden soll. |
$attrib
mandatory |
Der Name des Attributs, welches für die Definition $name verfügbar gemacht werden soll.
|
Daten dauerhaft schreiben/lesen
FileRead
($error, @content) = FileRead($filename);
($error, @content) = FileRead($param)
Die Funktion FileRead() liest den Inhalt der Datei $filename
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 $param
gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.
Parameter:
Parameter | Bedeutung |
---|---|
$filename
mandatory |
Der Dateisystempfad der Datei die eingelesen werden soll. |
$param
mandatory |
Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wiefolgt übergeben werden:
Die Variable |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält $error den Wert undef oder "" (Leerstring).
|
@content |
Der Inhalt der gewünschten Datei als zeilenweises Array. Im Falle eines Fehlers beim Lesen trägt dieses Array den Wert undef
|
FileWrite
$error = FileWrite($filename, @content);
$error = FileWrite($param, @content)
Die Funktion FileWrite() schreibt den übergebenen Inhalt @content
in die Datei $filename
. 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 $param
gesetzt werden in dem ein spezieller Wert den Zugriff auf das Dateisystem forciert.
Parameter:
Parameter | Bedeutung |
---|---|
$filename
mandatory |
Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll. |
$param
mandatory |
Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wiefolgt übergeben werden:
Die Variable |
@content
mandatory |
Die zu schreibenden Daten als ein Array von Zeilen (ohne Newline am Ende jeder Zeile). |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält $error den Wert undef
|
setKeyValue
$error = setKeyValue($key, $value)
Die Funktion setKeyValue() speichert die Daten $value
unter dem Schlüssel $key
ab. Die Daten werden in einer Datei auf dem Dateisystem (oder configDB) gespeichert und sind somit persistent auch nach einen Neustart von FHEM verfügbar. Die Daten welche in $value
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:
Parameter | Bedeutung |
---|---|
$key
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. |
$value
mandatory |
Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten.
Wenn |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Schreiben der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält $error den Wert undef
|
getKeyValue
($error, $value) = getKeyValue($key)
Die Funktion getKeyValue() gibt Daten, welche zuvor per setKeyValue()
gespeichert wurden, zurück.
Parameter:
Parameter | Bedeutung |
---|---|
$key
mandatory |
Der eindeutige Schlüssel als Zeichenkette unter dem die Daten gespeichert wurden. |
Rückgabewert:
Rückgabe | Bedeutung |
---|---|
$error |
Im Falle eines Fehlers beim Lesen der Daten ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält $error den Wert undef
|
$value |
Die Daten, welche unter dem gegebenen Schlüssel $key hinterlegt sind. Wenn keine Daten zu dem Schlüssel existieren, besitzt $value den Wert undef
|
Logging
Log
Log($verbose, $message)
Die Funktion Log() schreibt die Meldung $message
in das FHEM-Logfile, sofern $verbose
kleiner gleich dem globalen Attribut verbose
ist. Wenn $verbose
größer ist, als das globale Attribut verbose
, wird die Meldung nicht geloggt.
Parameter:
Parameter | Bedeutung |
---|---|
$verbose
mandatory |
Der Verbose-Level unter dem die Nachricht $message geloggt werden soll.
Ganzzahl zwischen 0 und 5 |
$message
mandatory |
Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. |
Log3
Log3($name, $verbose, $message)
Die Funktion Log3() schreibt die Meldung $message
in das FHEM-Logfile, sofern $verbose
kleiner gleich dem Attribut verbose
der Definition $name
ist. Wenn das Attribut verbose
in der Definition $name
nicht gesetzt ist, wird gegen das globale Attribut verbose
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:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Name der Definition wogegen geprüft werden soll. Wenn $name in FHEM nicht existiert, oder den Wert undef besitzt, wird der Parameter $verbose gegen das globale Attribut verbose geprüft.
|
$verbose
mandatory |
Der Verbose-Level unter dem die Nachricht $message geloggt werden soll.
Ganzzahl zwischen 0 und 5 |
$message
mandatory |
Die Log-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. |
Debug
Debug($message)
Die Funktion Debug() schreibt die Meldung $message
mit dem Präfix DEBUG>
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:
Log(1, "DEBUG>".$message);
Parameter:
Parameter | Bedeutung |
---|---|
$message
mandatory |
Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll. |
Status-Abfragen
IsDisabled
$status = IsDisabled($name)
Die Funktion IsDisabled() prüft, ob die Definition $name
aktuell deaktiviert (Attribute: disabled/disabledForIntervals) oder durch den Nutzer inaktiv geschaltet wurde (STATE: inactive
). Je nachdem ob die Definition deaktiviert/inaktiv ist, gibt sie einen entsprechenden Wert größer 0
zurück. Wenn die Definition aktiv ist, gibt die Funktion den Wert 0
zurück.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition aktiv/inaktiv ist.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status der Definition. Je nach Status sind folgende Werte möglich:
0 - Definition ist aktiv |
IsDummy
$status = IsDummy($name)
Die Funktion IsDummy() prüft, ob die Definition $name
in den Dummy-Modus versetzt wurde (Attribut: dummy
). Wenn die Definition in den Dummy-Modus gesetzt ist, gibt IsDummy() den Wert 1
zurück, andernfalls 0
.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition im Dummy-Modus ist.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status der Definition. Je nach Status sind folgende Werte möglich:
0 - Definition ist aktiv |
IsIgnored
$status = IsIgnored($name)
Die Funktion IsIgnored() prüft, ob die Definition $name
durch den User ignoriert wird (Attribut: ignore
). Wenn die Definition durch den User ignoriert wird, gibt IsIgnored() den Wert 1
zurück, andernfalls 0
.
Diese Funktion kann dabei in typischen if-Konstrukten direkt verwendet werden um zu prüfen, ob eine Definition ignoriert wird.
Parameter:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name welcher geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status der Definition. Je nach Status sind folgende Werte möglich:
0 - Definition ist aktiv |
IsIoDummy
$status = IsIoDummy($name)
Die Funktion IsIoDummy() prüft, ob das zugeordnete IO-Device der Definition $name
in den Dummy-Modus versetzt wurde (Attribut: dummy
). Wenn das IO-Device in den Dummy-Modus gesetzt ist, gibt IsIoDummy() den Wert 1
zurück, andernfalls 0
.
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:
Parameter | Bedeutung |
---|---|
$name
mandatory |
Der Definitions-Name dessen IO-Device geprüft werden soll. |
Rückgabewerte:
Rückgabewert | Bedeutung |
---|---|
$status |
Der Status des IO-Devices der Definition. Je nach Status sind folgende Werte möglich:
0 - IO-Device der Definition ist aktiv |
Sonstiges
configDBUsed
$status = configDBUsed()
Die Funktion configDBUsed() prüft, ob in der aktuellen FHEM-Umgebung configDB verwendet wird und gibt in diesem Fall den Wert 1
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:
Rückgabewert | Bedeutung |
---|---|
$status |
Folgende Werte sind möglich: 0 - configDB wird nicht verwendet |
getUniqueId
$uniqueID = getUniqueId()
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:
Rückgabewert | Bedeutung |
---|---|
$uniqueID |
Eine Zeichenkette in Hexadezimaldarstellung welche pro Installation eindeutig ist. |