DevelopmentModuleAPI

Bitte beachten: letztendlich entscheidend ist immer der Perl-Code, Unstimmigkeiten sollten im Fhem-Forum angemerkt (oder hier berichtigt) werden!

Please note: in the end it is always the Perl code itself that is relevant; please report errors and omissions in the fhem forum (or correct them here)!

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.

Command handling

AnalyzeCommand

AnalyzeCommand ermöglicht das Parsen und die Ausführung eines FHEM-Befehls, wie in FHEMWEB im Kommandoeingabefeld enthalten.

AnalyzeCommand ($cl, $cmd)

Parameter	Bedeutung
`$cl` might be undef	Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung)
`$cmd` mandatory	Kommandos, die ausgeführt werden sollen. Beispiel: define dummy1 dummy { Log3(undef, 1, "Hallo");}

AnalyzeCommandChain

AnalyzeCommandChain ermöglicht das Parsen und die Ausführung von FHEM-Befehlen, wie in FHEMWeb im Kommandoeingabefeld enthalten.

AnalyzeCommandChain ($cl, $cmds)

Parameter	Bedeutung
`$cl` might be undef	Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung)
`$cmds` mandatory	Kommandos, das ausgeführt werden soll, durch ; getrennt. Beispiel: define dummy1 dummy; list dummy1

Diverse

ReplaceSetMagic

($err, @result) = ReplaceSetMagic($hash, $nsplit, @elements)

Parameter	Bedeutung
`$hash` might be undef	Devicehash für die Ausführung des Kommandos in einem spezifischen Kontext eines Devices (Quelle des Befehles z.B. für Berechtigungsprüfung)
`$nsplit` Zahl	Begrenzung für den Split des Ergebnisstrings nach erfolgter Ersetzung (siehe elements)
`@elements` mandatory	Parameterarray mit Strings Die Elemente des übergebenen Arrays werden in einem String getrennt duch Leerzeichen zusammengefasst.

Rückgabe	Bedeutung
`$err`	Im Fehlerfall: Fehlermeldung sonst undef
`@result`	Ergebnis der Ersetzung von Readings und Perl Aufrufen im Parameterarray. Die Elemente des übergebenen Arrays werden in einem String, getrennt durch Leerzeichen, zusammengefasst und im Rückgabewert wieder in ein Array (unter Berücksichtigung von nsplit als Begrenzung für den perl-Split-Aufruf) zerlegt.

Time / Timestamp

FmtDateTimeRFC1123

$timestampGMT = FmtDateTimeRFC1123($time)

Parameter	Bedeutung
`$time` might be undef	Zeitangabe wie sie von der `time` Funktion zurückgegeben wird `Mon, 15 Feb 2016 20:52:20 GMT`

Rückgabe	Bedeutung
`$timestampGMT`	Zeitstempel GMT (Greenwich Mean Time) wie er in RFC1123 beschrieben wird. Diese werden zum Beispiel bei http verwendet. `Mon, 15 Feb 2016 20:52:20 GMT`

FmtDateTime

$timestamp = FmtDateTime($time)

Parameter	Bedeutung
`$time`	Zeitangabe wie sie von der `time` Funktion zurückgegeben wird

Rückgabe	Bedeutung
`$timestamp`	Zeitstempel in lokaler Zeitzone im Format `2016-02-16 19:34:24`

TimeNow

$timestamp = TimeNow( )

Rückgabe	Bedeutung
`$timestamp`	Zeitstempel der aktuellen Uhrzeit in lokaler Zeitzone im Format `2016-02-16 19:34:24` Benutzt FmtDateTime

Readings

Die verschiedenen Funktionen zu Readings sind hier beschrieben:

DevelopmentIntroduction und DevelopmentModuleIntro

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	Bedeutung
`$timestamp`	Angabe eines UNIX-Timestamp, wann der Timer ausgeführt werden soll (bspw: `gettimeofday() + 30` um in 30 Sekunden etwas zu starten)
`$functionName`	Der Name der Funktion welche ausgeführt werden soll zum angegebenen Zeitpunkt (bspw: "MODULNAME_GetStatus")
`$arg`	Der Übergabeparameter welchen die genannte Funktion zum Ausführungszeitpunkt erhalten soll. Typischerweise ist das meistens $hash.
`$waitIfInitNotDone`	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)

Die Funktion RemoveInternalTimer löscht möglicherweise noch anstehende Timer welche mit dem Übergabeparameter $arg gescheduled sind.

Parameter	Bedeutung
`$arg`	Der Übergabeparameter nach wem gesucht wird. Alle Timer die mit diesem Übergabeparameter noch anstehen, werden dabei gelöscht.

Datenabfrage-/auslesen

ReadingsVal

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`	Der Definitions-Namen aus dem das gewünschte Reading ausgelesen werden soll.
`$reading`	Der Name des Readings welcher ausgelesen werden soll.
`$default`	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

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	Bedeutung
`$name`	Der Definitions-Namen aus dem der Zeitstempe für das gewünschte Reading ausgelesen werden soll.
`$reading`	Der Name des Readings für welches der Zeitstempel ausgelesen werden soll.
`$default`	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 `2016-02-16 19:34:24`

ReadingsNum

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	Bedeutung
`$name`	Der Definitions-Namen aus dem ein numerischer Wert für das gewünschte Reading ausgelesen werden soll.
`$reading`	Der Name des Readings aus dem ein numerischer Wert ausgelesen werden soll.
`$default`	Der Standardwert der zurückgegeben werden soll, sofern das Reading nicht existiert.

Rückgabewert:

Rückgabe	Bedeutung
`$num`	Numerischer Wert des gewünschten Readings oder `$default`, wenn es nicht existiert.

AttrVal

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`	Der Definitions-Namen aus dem das gewünschte Attribut ausgelesen werden soll.
`$attribute`	Der Name des Attributs, dessen Wert ausgelesen werden soll.
`$default`	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

AttrVal($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`	Der Definitions-Namen aus dem das gewünschte Internal ausgelesen werden soll.
`$internal`	Der Name des Internals, dessen Wert ausgelesen werden soll.
`$default`	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($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`	Der Definitions-Namen aus dem der Status ausgelesen werden soll.

Rückgabewert:

Rückgabe	Bedeutung
`$value`	Status der gewünschten Definition

OldValue

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`	Der Definitions-Namen aus dem der Status ausgelesen werden soll.

Rückgabewert:

Rückgabe	Bedeutung
`$value`	vorherige Status der gewünschten Definition

OldTimestamp

OldValue($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`	Der Definitions-Namen aus dem der Status ausgelesen werden soll.

Rückgabewert:

Rückgabe	Bedeutung
`$timestamp`	Zeitstempel in lokaler Zeitzone im Format `2016-02-16 19:34:24`

Fehlt noch

Log
Log3
IsDisabled
IsDummy
IsIgnored
IsIoDummy
~~InternalTimer~~
~~RemoveInternalTimer~~
configDBUsed
devspec2array
~~FmtTime~~
EvalSpecials
DoTrigger
~~InternalVal~~
~~ReadingsVal~~
~~ReadingsNum~~
~~ReadingsTimestamp~~
~~Value~~
~~OldValue~~
~~OldTimestamp~~
~~AttrVal~~
readingsBeginUpdate
readingsBulkUpdate
readingsEndUpdate
readingsSingleUpdate
FileRead
FileWrite
getUniqueId
getKeyValue
setKeyValue
Debug