Quelltext der Seite Benachrichtigungen von der Homematic

Manche der im nächsten Abschnitt folgenden Programme müssen mich irgendwie über ihr Ergebnis benachrichtigen. Dazu gibt es eine Reihe von sehr unterschiedlichen Möglichkeiten.

=E-Mail=
Eine Benachrichtigung per E-Mail ist relativ einfach und flexibel. Hierfür gibt es bei der Homematic mehrere Möglichkeiten.

==E-Mail Addon von Jens Maus==
Das Addon kann man unter https://github.com/jens-maus/hm_email/releases oder auch unter https://www.homematic-inside.de/addons beziehen. Seine Installation und Nutzung ist an vielen Stellen ausführlich beschrieben, z.B. unter https://www.christian-luetgens.de/homematic/e-mail/einrichtung/Einrichtung.htm .

Hier kann man eine Mail vorbereiten (hier Nummer 10) und dann, eventuelle um einen Parameter erweitert einfach aufrufen:
 dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State("/etc/config/addons/email/email 10 "+"geöffnet");


==Service von EasySmartHome==
Man kann damit ohne vorbereitete Mail alle Informationen an eein Script übergeben, das zu der CloutMatic umgebung gehört:

 dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State("/etc/config/addons/mh/email.sh " + "Homematic:+Fenster+geöffnet " + "Fenster+im+Arbeitszimmer+geöffnet " + "ich@meine-maildomain.de");

Im Detail ist das unter http://kb.easy-smarthome.de/CloudMatic_NotifyMe_-_Mail-Versand beschrieben. Wichtig sind hier jeweils die Leerzeichen am Ende. Das Script erwartet drei Parameter:
# Betreff
# Text
# Mailadresse

Also müssen diese Angaben durch Leerzeichen getrennt sein und dürfen selber keine Leerzeichen beinhalten.

==Ein kleines PHP-Script==
Man kann auch ohne das E-Mail Addon auskommen, wenn man einen eigenen Server mit PHP und Mail-Funktionalität zur Verfügung hat. Ich habe mir dazu das folgende kleine PHP-Script erstellt_

 <?php
 #Programm für die einfache Mailnutzung im Homematic-System
 if (strlen($_REQUEST['mailto'])<2) exit("Bitte Empfänger angeben");
 $empfaenger=$_REQUEST['mailto'];
 
 if (strlen($_REQUEST['mailbetreff'])<2) exit("Bitte Betreff angeben");
 $betreff="=?utf-8?b?".base64_encode(utf8_encode($_REQUEST['mailbetreff']))."?=";
 
 if (strlen($_REQUEST['mailtext'])<2) exit("Bitte Mailtext angeben");
 $mailtext=utf8_encode($_REQUEST['mailtext']);
 
 if ($_REQUEST['key']<>'08154711') exit("Sicherheitscode falsch");
 
 $absender="homematic@meine-maildomain.de";
  
 $headers   = array();
 $headers[] = "MIME-Version: 1.0";
 $headers[] = "Content-type: text/plain; charset=utf-8";
 $headers[] = "From: {$absender}";
 $headers[] = "Reply-To: {$absender}";
 $headers[] = "X-Mailer: PHP/".phpversion();
 
 mail($empfaenger, $betreff, $mailtext,implode("\r\n",$headers));
 echo "Mail versendet";
 
 ?>

Dieses Script kann ich jetzt von der CCU aus in Programmen aufrufen:
 dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State("/usr/bin/wget -O /dev/null " # "'http://www.debacher.de/homematic.php?key=08154711&mailto=uwe@meine-maildomain.de&mailbetreff=" # sendbetreff # "&mailtext=" # sendmail # "'");

Wobei die Homematic-Variablen ''sendmail'', ''sendbetreff'' vorher im jeweiligen Programm gesetzt werden. Der ''key'' soll nur eine missbräuchliche Nutzung erschweren.

=Per Nachrichten PUSH=
In der Regel hat man auf dem Smartphone eine Reihe von Anwendungen laufen, die in der Lage sind PUSH-Nachrichten zu verarbeiten. Einige davon besitzen eine API, über die man auch Nachrichten aus Scripten heraus erzeugen kann.

==Telegram-Bot==
Eine sehr interessante Möglichkeit ist die Nutzung des Messengers Telegram. Der bietet über eine API die Möglichkeit aus einem Script heraus (als Bot) Nachrichten zu verschicken. Man braucht dafür quasi zwei Accounts:
* Einen (ggf. auch mehrere) persönlichen Account, den man z.B. auf dem Smartphone in der App Telegram eingerichtet hat
* Einen zusätzlichen Bot-Account, der an kein Gerät gebunden ist.

Beschrieben ist die Einrichtung des Systems bei [https://www.elv.de/HomeMatic-Know-how-Teil-27-Nachrichtenversand/x.aspx/cid_726/detail_62541 ELV] und unter https://technikkram.net/2016/03/push-nachrichten-via-homematic-ccu2-versenden .

Deshalb hier nur in Kürze die einzelnen Schritte mit zusätzlichen Anmerkungen:
# Installation der App Telegram auf dem Smartphone
# Beim ersten Öffnen der App legt man einen normalen Benutzer-Account an.
# Man startet einen Chat mit dem Benutzer ''BotFather'', dem Vater aller Bot
# Von BotFather bekommt man eine Anleitung geschickt, wichtig ist hier vor allem /newbot
# Also gibt man den Befehl /newbot im Chat mit BotFather ein
# BotFather fragt nach dem Namen des Bots, das ist der Name, der in Chats später zu sehen sein wird
# BotFather fragt nach einem Benutzernamen. Der später nur einmal benötigt, muss aber eindeutig sein
# Wenn BotFather einverstanden ist, dann kommt eine längere Nachricht, mit der später benötigten API Key bzw. API-Token. Bei mir besteht dieses Token aus 9 Ziffern gefolgt von einem Doppelpunkt und dann noch einmal 35 Zeichen
# Nun brauchen wir noch die Chat-ID des normalen Benutzers, dazu sucht man im Telegram-Client den Bot, über den Benutzernamen (Schritt 7), und schickt ihm eine beliebige Nachricht. Eventuell ist es dazu hilfreich sich am Desktop-Rechner unter https://web.telegram.org/ anzumelden.
# Die Chat-ID findet sich im Browser in der Antwort auf den Seitenaufruf https://api.telegram.org/bot123456789:ABCD2fGhIj5LmnOPQ7_TUvwXYZ123456789/getUpdates . Bei mir besteht die ID aus 9 Ziffern<br>Etwas einfacher kommt man auf einem Android-Phone an die ID. Hier geht man auf: Einstellung -> Nutzer und Konten Telegram (hier steht dann die Ziffernkette)

Nun kann man von jedem Browser aus Nachrichten an den Telegram-Nutzer schicken, einfach mit folgender URL
 https://api.telegram.org/bot123456789:ABCD2fGhIj5LmnOPQ7_TUvwXYZ123456789/sendMessage?chat_id=123456789&text=Meine+Nachricht

Der Zugriff muss mittels https erfolgen, daher sieht dann der entsprechende wget-Aufruf folgendermaßen aus:
 wget --no-check-certificate -q  "https://api.telegram.org/bot123456789:ABCD2fGhIj5LmnOPQ7_TUvwXYZ123456789/sendMessage?chat_id=123456789&text=Meine+Nachricht+Nummer5"

Mit den Parametern wird die Überprüfung des Webseiten-Zertifikats unterbunden und auf die Rückgabe des Ergebnisses verzichtet.

In einem Homematic-Programm könnte das dann folgendermaßen aussehen (die Variablen sendbetreff und sendmail werden im vorangehenden Code belegt):
 
 string turl = "'https://api.telegram.org/bot123456789:ABCD2fGhIj5LmnOPQ7_TUvwXYZ123456789'";
 string post = "'chat_id=123456789&text="#sendbetreff.ToUTF8().UriEncode()#"\r\n\r\n"#sendmail.ToUTF8().UriEncode()#"'";
 
 dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State("/usr/bin/wget --no-check-certificate -q -O /dev/null --post-data="#post#" "#turl);

Wichtig ist hier, dass die Strings zweifach, aber unterschiedlich, in Anführungsstriche gesetzt werden. Die doppelten Anführungsstriche werden von der CCU benötigt, wir geben ja Strings an. Die einfachen Anführungsstriche sind für ''wget'' notwendig. Statt der einfachen Anführungsstriche könnte man auch den doppelten Anführungsstrich escapen: \" .

Sollen im Text und im Betreff auch Umlaute und Sonderzeichen erlaubt sein, so muss man diese für die CCU passen encodieren. Dafür dienen die Stringfunktionen ToUTF8() und UriEncode(). Diese beiden Funktionen stehen erst seit [https://www.eq-3.com/Downloads/eq3/download%20bereich/hm_web_ui_doku/HM-Skript_Teil_1_Sprachbeschreibung_V2.2.pdf Version 2.29.22 (September 2017)] zur Verfügung. Viele Anleitungen im Netz gehen daher noch umständlichere Wege.

==EasySmartHome==
Über die Cloudmatic-Dienste kann man auch PUSH-Nachrichten an die EasyApp verschicken. Das ist unter http://kb.easy-smarthome.de/CloudMatic_NotifyMe_-_Push-Mitteilungen ausführlich beschrieben und funktioniert ganz ähnlich, wie mit Telegram.

Auch hier muss man sich eine ID für die App ermitteln und kann dann im Prinzip beliebig viele Endgeräte mit Informationen versorgen.

==Pushover==
In dem ELV-Dokument unter https://www.elv.de/HomeMatic-Know-how-Teil-27-Nachrichtenversand/x.aspx/cid_726/detail_62541 ist noch der Dienst Pushover beschrieben. Mit diesem Dienst habe ich aber keine eigenen Erfahrungen gemacht.

=Frameworks=
Der Versand von Meldungen ist eventuell bei einigen Programmen sehr wichtig. Da bietet es sich an diesen Teil aus den Programmen auszulagern und zu zentralisieren. Die Idee dabei ist folgende:

Die normalen Programme setzen nur eine Systemvariable, und zwar schreiben sie den zu übermittelnden Text in diese Variable. Das eigentliche Benachrichtigungsprogramm achtet auf Aktualisierungen dieser Variablen und wenn die aktualisiert wird und nicht leer ist, dann wird ihr Inhalt verschickt.

==Systemvariable==
Ich habe mir folgende Systemvariable vom Typ String angelegt:
* Text.Mail.Uwe
* Text.Telegram.Uwe

==Mail==
Das Programm heißt ''Info.Mail.Uwe'', passend zur Systemvariablen.

[[Datei:Homematic-51.png|700px]]

Wenn die Variable aktualisiert wird und der Inhalt leer ist, dann passiert nichts. Wenn der Inhalt nicht leer ist, dann wird das folgende Script ausgeführt:

 ! HomeMatic-Script
 ! Benachrichtigungs-Framework: E-Mail
 ! https://www.debacher.de/wiki/Benachrichtigungen_von_der_Homematic
 
 object sysvariable = dom.GetObject ("Text.Mail.Uwe");
 string nachricht=sysvariable.Value();
 
 if (nachricht.Trim() != "") {
  string betreff = nachricht.StrValueByIndex(":", 0).ToUTF8().UriEncode() # " ";
  string inhalt  = nachricht.StrValueByIndex(":", 1).ToUTF8().UriEncode() # " ";
  dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State("/etc/config/addons/mh/email.sh " # betreff # inhalt  # "uwe@meine-maildomain.de");
  sysvariable.State("");
 }

Zuerst wird also die Sysvariable gesucht ihr Wert ermittelt und in die lokale Variable ''nachricht'' geschrieben. Nur wenn die Nachricht nicht leer ist, dann wird sie in die Bestandteile ''betreff'' und ''inhalt'' aufgesplittet, wobei der Doppelpunkt das Trennzeichen ist. Die beiden Variablen werden dann noch passend HTML-kodiert

Nun werden die drei Komponenten ''betreff'', ''inhalt'' und ''Mailadresse'' an das Mailscript übergeben. Wichtig ist, dass dazwischen immer ein Leerzeichen gesetzt ist.
Zuletzt wird dann die Systemvariable geleert.

Hier noch ein kleines Testprogramm, welches einfach den Inhalt der Variablen setzt:

[[Datei:Homematic-53.png|700px]]

Wichtig ist hierbei der Doppelpunkt, der Betreff und Inhalt trennt. Ich wollte einfach nicht mit zwei Variablen arbeiten müssen.

==Telegram==
Der Homematic-Teil von ''Info.Telegram.Uwe'' sieht aus wie der vom Mailprogramm.

[[Datei:Homematic-52.png|700px]]

Auch das Script hat ein paar Ähnlichkeiten

 ! HomeMatic-Script
 ! Benachrichtigungs-Framework: Telegram
 ! https://www.debacher.de/wiki/Benachrichtigungen_von_der_Homematic
 
 object sysvariable = dom.GetObject ("Text.Telegram.Uwe");
 string nachricht=sysvariable.Value();
 
 if (nachricht.Trim() != "") {
  string adresse = "https://api.telegram.org/bot123456789:ABCD2fGhIj5LmnOPQ7_TUvwXYZ123456789/sendMessage";
  string inhalt  = "?chat_id=123456789&parse_mode=Markdown&text=" # nachricht.ToUTF8().UriEncode();
  dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State("/usr/bin/wget --no-check-certificate -q -O /dev/null '" # adresse # inhalt + "'");
  sysvariable.State("");
 }

Gegenüber der bisherigen Beschreibung für Telegram ist hier noch ''&parse_mode=Markdown'' mit eingebaut. Dadurch kann man bestimme Auszeichnungen, wie Fett und Kursiv mit in der Nachricht unterbringen. Ich habe da viel auf den Seiten [http://www.christian-luetgens.de/homematic/telegram/mehrtelegramframework/Mehr_T-Framework.htm Christian Lütgens] lernen können.

Auch hier noch ein kleines Testprogramm:

[[Datei:Homematic54.png|700px]]

Hier erzeuge ich eine zweizeilige Ausgabe. Die Zeichenfolge \r\n bewirkt eine neue Zeile und die Sterne klammern den fett darzustellenden Bereich.