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.

FHEM-Befehlsausführung

AnalyzeCommand

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

AnalyzeCommand ($cl, $cmd)

Parameter:

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");}

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 das Parsen und die Ausführung von FHEM-Befehlen, wie in FHEMWeb im Kommandoeingabefeld enthalten.

AnalyzeCommandChain ($cl, $cmds)

Parameter:

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

Rückgabewerte:

Rückgabewert	Bedeutung
$error	Fehlermeldungen, die beim ausführen der Kommandos aufgetreten sind. Wenn keine Fehlermeldungen aufgetreten sind, wird undef zurückgegeben.

Time / Timestamp

FmtDateTimeRFC1123

$timestampGMT = FmtDateTimeRFC1123($time)

Gibt die aktuelle Zeit nach RFC 1123 formatiert zurück.

Parameter:

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ückgabewerte:

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)

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	Zeitangabe wie sie von der time Funktion zurückgegeben wird. Standardmäßig handelt es hierbei um einen UNIX-Zeitstempel.

Rückgabewerte:

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

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 2016-02-16 19:34:24 Benutzt die Funktion 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

Daten dauerhaft schreiben/lesen

FileRead

FileRead($filename)
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	Der Dateisystempfad der Datei die eingelesen werden soll.
$param	Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wiefolgt übergeben werden: { FileName => $filename, ForceType => "file" } Die Variable $filename enthält dabei den lokalen Dateisystempfad zu der gewünschten Datei.

Rückgabewert:

Rückgabe	Bedeutung
$err	Im Falle eines Fehlers beim Lesen der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Lesevorgang erfolgreich enthält $err 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

FileWrite($filename, @content)
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	Der Dateisystempfad der Datei in welche der Inhalt geschrieben werden soll.
$param	Um im Falle der Nutzung von configDB den Zugriff auf das lokale Dateisystem zu erzwingen muss ein Parameter-Hash wiefolgt übergeben werden: { FileName => $filename, ForceType => "file", NoNL => 0 } Die Variable $filename enthält dabei den lokalen Dateisystempfad der zu schreibenden Datei. Optional kann man den Wert NoNL auf 1 setzen um kein Newline (\n) als Trennzeichen zwischen den einzelnen Zeilen zu erzeugen.

Rückgabewert:

Rückgabe	Bedeutung
$err	Im Falle eines Fehlers beim Schreiben der Datei ist dieser Wert mit einer Fehlermeldung als Zeichenkette gefüllt. Ist der Schreibvorgang erfolgreich enthält $err den Wert undef

setKeyValue

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	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	Die zu speichernden Daten als Zeichenkette ohne Zeilenumbruch. Die Daten dürfen dabei keine Zeilenumbrüche enthalten. Wenn $value den Wert undef besitzt, werden zuvor gespeicherte Daten gelöscht.

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

getKeyValue($key)

Die Funktion getKeyValue() gibt Daten, welche zuvor per setKeyValue() gespeichert wurden, zurück.

Parameter:

Parameter	Bedeutung
$key	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 Schreibvorgang 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	Der Verbose-Level unter dem die Nachricht $message geloggt werden soll. Ganzzahl zwischen 0 und 5
$message	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	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	Der Verbose-Level unter dem die Nachricht $message geloggt werden soll. Ganzzahl zwischen 0 und 5
$message	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	Die Debug-Meldung als Zeichenkette, welche in das FHEM-Logfile geloggt werden soll.

Status-Abfragen

IsDisabled

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	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 1 - Definition ist durch das Attribut disable deaktiviert 2 - Definition ist durch das Attribut disabledForIntervals deaktiviert 3 - Definition ist durch den User inaktiv geschaltet. Der STATE der Definition ist inactive.

IsDummy

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	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 1 - Definition ist im Dummy-Modus

IsIgnored

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	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 1 - Definition wird ignoriert

IsIoDummy

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	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 1 - IO-Device der Definition ist im Dummy-Modus

Sonstiges

configDBUsed

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 1 - configDB wird verwendet

getUniqueId

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.

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