Mini-Framework

Mit etwas Vorbereitung kann man sehr komfortabel aus allen WebUI-Programmen eigene E-Mails versenden

Um vorgefertigte E-Mails von der CCU zu versenden, muss man jene im Add-on zunächst anlegen. Anschließend kann man in WebUI-Programmen ein Script erstellen, das dann über einen Parameter die vorgefertigte E-Mail versendet. Das ist umständlich.

Man kann auch ein Tcl-Script einbinden, um irgendwelche Parameter zu übergeben. Die meisten Anleitungen im Internet fummeln für spezielle Anwendungen ein speziell angepasstes Script da rein – was bedeutet, dass man für die nächste Anwendung wieder mit Tcl rumfummeln darf. Dabei gibt es nichts nervigeres als Tcl …

Mit dem Mini-Framework braucht man nur einmal das Add-on mit einigen Systemvariablen und einem Programm einzurichten. Danach kann man direkt aus WebUI-Programmen heraus beliebige E-Mails senden, ohne sich mit E-Mail-Vorlagen oder Tcl befassen zu müssen.

Variablen in HomeMatic-Scripten

Die CCU hatte früher ein Limit von maximal 200 Variablen, das mit Firmware-Version 2.29.18 aufgehoben wurde. Dieses Limit bezog sich auf alle Variablen, die in allen Scripten verwendet werden. Gemeint sind Variablen, die direkt im Script definiert werden: object x; object y; var z;

Wenn Scripte nicht mehr funktionieren und bei der Prüfung unerklärliche Syntax-Fehler auftreten, sollte versuchsweise dieses Programm wieder gelöscht oder deaktiviert werden – oder, noch besser, auf die aktuelle Firmware-Version aktualisiert werden.

Strings in HomeMatic-Scripten

Durch String-Verwendung in HomeMatic-Scripten kann die CCU fehlerhaft arbeiten, instabil werden oder sogar abstürzen. Grundsätzlich gilt: Je öfter mit Strings hantiert wird, desto eher führt dies zu Problemen.

Ich empfehle daher, nach Umsetzung dieser Anleitung die CCU unter Beobachtung zu halten.

system.Exec();

Wenn system.Exec() verwendet wird, um aus HomeMatic-Scripten heraus Systemfunktionen auf der CCU zu starten, kann dies zu Fehlfunktionen der CCU führen, die einen Neustart erforderlich machen. Außerdem „hängt“ die CCU, solange externe Befehle ausgeführt werden.

Installieren Sie den CUx-Daemon, dessen Exec-Funktion für diese Probleme weniger anfällig ist.

Benennung von Systemvariablen

Prinzipiell kann man Systemvariablen – so wie allen Objekten in der CCU – beliebige Namen geben, also z. B. auch Umlaute und Sonderzeichen verwenden. Ich empfehle jedoch, sich auf reguläre Buchstaben (a-z, A-Z) zu beschränken: Bei Umlauten und Sonderzeichen besteht die Gefahr, dass Systemvariablen in Scripten nicht überall gefunden werden.

So funktioniert der Versand

Am Ende dieser Anleitung geht der E-Mail-Versand so:

Mehr muss man nicht tun, um E-Mails zu versenden.

Das passiert im Hintergrund:

Alles, was umständlich ist, muss nur einmal eingerichtet werden. Die Anwendung ist danach kinderleicht.

Meine „Frameworks“

Es gibt mittlerweile vier Varianten meines „Mini-Frameworks“.

Lassen Sie sich nicht erschrecken: Im Grunde ist alles das „Mini-Framework“ mit kleinen Anpassungen für verschiedene Anwendungsfälle. Am einfachsten beginnen Sie mit dem normalen Mini-Framework. Wenn Sie Lust haben, können Sie danach die anderen Varianten ausprobieren.

Vor der Einrichtung des Mini-Frameworks muss das E-Mail-Add-on eingerichtet sein und funktionieren.

Systemvariable anlegen

Zunächst brauchen wir zwei Systemvariable vom Typ „Zeichenkette“. Ich habe sie E-Mail.Subject und E-Mail.Body genannt. Wer andere Namen nutzt, muss diese im weiteren Verlauf entsprechend anpassen.

Den E-Mail-Empfänger speichere ich in den Vorlagen – sonst hätte ich noch eine dritte Zeichenkette für die E-Mail-Adresse angelegt. Wer’s mag, kann das so tun.

Eine dritte Systemvariable hat den Typ „Werteliste“. Ich nenne sie E-Mail.Versand.

Ich habe mich dafür entschieden, zwei verschiedene Vorlagen zu verwenden: Eine für Fehler, bei der die E-Mails direkt in meinem Posteingang landen und auf dem iPhone angezeigt werden, und eine für Statusmeldungen, deren E-Mails irgendwo in einen Ordner sortiert werden.

Meine Werteliste lautet entsprechend:

kein Versand;Fehler;Status

Was es mit den Vorlagen auf sich hat, wird unten noch etwas deutlicher – für den Moment reicht das Wissen, dass ich Status- und Fehler-E-Mails verschicken werde und die Liste daher diese Punkte enthält.

Tcl-Script erstellen

Das Tcl-Script wird im E-Mail-Add-on unter „Einstellungen“ / „Systemsteuerung“ / „E-Mail“ erstellt. Im Reiter „Tcl“ das folgende Script einfügen:

load tclrega.so

array set values [rega_script {

var subject = dom.GetObject("E-Mail.Subject").Value();
var body = dom.GetObject("E-Mail.Body").Value();

} ]

set subject $values(subject)
set body [encoding convertto $values(body)]

Wichtig: Wenn die Namen der Systemvariablen anders gewählt wurden, müssen sie in GetObject() unbedingt angepasst werden. Natürlich können auch die Variablennamen subject und body umbenannt werden – aber mal ehrlich, irgendwann ist auch mal Schluss mit der Individualisierung.

So, wie es ist, liest das Tcl-Script die Systemvariable E-Mail.Subject aus und speichert den Inhalt in der Variable $subject.

Für $body wird das Gleiche gemacht. Zusätzlich wird hier der Text in UTF-8 konvertiert, damit in der E-Mail auch Umlaute richtig angezeigt werden. Im Subject sind Umlaute leider nicht möglich.

An dieser Stelle können theoretisch auch weitere Variablen definiert werden, die später in E-Mails verwendet werden können. Mit $subject und $body ist aber eigentlich alles abgedeckt, was eine E-Mail braucht – was dann letztlich drinsteht, wird später über WebUI-Programme definiert. Darum brauche ich hier nicht mehr als diese beiden Variablen.

Mit „Übernehmen“ wird das Script gespeichert.

E-Mail-Vorlagen erstellen

Jetzt wird der Zusammenhang zwischen der Werteliste der Systemvariable E-Mail.Versand und den Vorlagen klar: Unter „E-Mails“ richte ich je eine Vorlage für Fehler-E-Mails und eine für Status-E-Mails ein.

Hätte ich meiner Werteliste weitere Optionen gegeben, zum Beispiel zusätzlich „Mail an Mama“ und „Alarm“, müsste ich hier auch für diese Optionen Vorlagen einrichten. Das Mini-Framework kann bis zu 9 Vorlagen nutzen.

$subject wird beim Versand durch den Wert von E-Mail.Subject ersetzt. Das Gleiche gilt entsprechend wieder für $body. Der restliche Text wird unverändert gesendet.

Waagerechte Striche wie in meinem Vorlagentext oben kann man mit einfachen Unterstrichen erzeugen, die man rechts unten auf der Tastatur findet:

_______________________

Eine Leerzeile drunter und fertig ist ein strukturierendes Element in Nur-Text-E-Mails.

Die zweite E-Mail wird genauso erstellt, nur dass an den entsprechenden Stellen „Status“ statt „Fehler“ steht. Hätte ich noch eine „Mail an Mama“ definiert, würde ich in der dritten Vorlage deren E-Mail-Adresse eintragen, für „Alarm“ würde ich noch eine vierte Vorlage einrichten usw.

Mir reichen meine zwei. Ich bin bescheiden.

Die Reihenfolge der Vorlagen entspricht der Reihenfolge der Optionen in der Werteliste.

Nicht den Haken bei „Tcl aktivieren“ vergessen – und den Klick auf „Übernehmen“, bevor zwischen den E-Mail-Vorlagen gewechselt wird.

Versandprogramm in der WebUI anlegen

Für den Versand erstelle ich ein WebUI-Programm.

Sobald die Systemvariable E-Mail.Versand auf „Fehler“ oder „Status“ gesetzt wird, wird das Script ausgeführt. Weitere Listeneinträge wie „Mail für Mama“ und „Alarm“ müssten ebenfalls hier definiert werden. Ich verwende „auslösen auf Aktualisierung“, damit in jedem Fall der E-Mail-Versand erfolgt, auch wenn die Systemvariable vorher nicht auf „kein Versand“ stand.

Wer sich fragt, warum ich jeden einzelnen Wert hier aufführen muss, findet vielleicht auf der Seite Die Logik von WebUI-Programmen die Lösung. Vielleicht auch nicht. Lange Geschichte.

Das Script, welches ausgeführt wird, sieht so aus:

! HomeMatic-Script
! MINI-FRAMEWORK
! http://www.christian-luetgens.de/homematic/e-mail/framework/Mini-Framework.htm

object subject=dom.GetObject ("E-Mail.Subject");
object body=dom.GetObject ("E-Mail.Body");
object versand=dom.GetObject ("E-Mail.Versand");

if ((subject.Value() != "") && (body.Value() != "") && (versand.Value() > 0)) {

  string stdout;
  string stderr;
  system.Exec ("/etc/config/addons/email/email 0" # versand.Value(), &stdout, &stderr);

  dom.GetObject ("E-Mail.Subject").State ("");
  dom.GetObject ("E-Mail.Body").State ("");
  dom.GetObject ("E-Mail.Versand").State (0);
}

!  Ende des Scripts

Das Script prüft, ob die Systemvariablen gefüllt sind – man weiß ja nie. Wenn alles OK ist, wird der E-Mail-Versand angestoßen, wobei der ausgewählte Wert von E-Mail.Versand als Parameter an das E-Mail-Add-on übergeben wird.

Die Systemvariablen werden am Ende des Scripts geleert – so kann man nachvollziehen, dass das Script durchgelaufen ist. Außerdem ist so sichergestellt, dass tatsächlich nur dann E-Mails verschickt werden, wenn ein frischer Text in die Systemvariablen geschrieben wurde.

Damit ist das Mini-Framework fertig und ich kann es in WebUI-Programmen einsetzen.

Nächste Schritte

Navigation