Telegram-Framework

Meine Liebe zu Mini-Frameworks macht auch vor Telegram nicht Halt

Das Telegram-Framework (kurz T-Framework) funktioniert am Ende genauso bequem wie mein Mini-Framework für den E-Mail-Versand. Eigentlich sogar noch bequemer – denn es muss nur eine Systemvariable gesetzt werden und fertig.

Zur Installation muss ein Telegram-Bot angelegt sein. Sie benötigen dessen HTTP-Token und Chat-ID.

Neue Script-Funktionen

Mit Firmware 2.29.22 wurden neue Funktionen in der Scriptsprache der CCU eingeführt, die auf dieser Seite genutzt werden. Achten Sie darauf, als Logikschicht-Version in den Systemeinstellungen der CCU nicht „Legacy“ zu wählen.

Wenn Sie eine ältere Firmware verwenden oder als Logikschicht-Version „Legacy“ ausgewählt haben, werden Sie Script-Fehler angezeigt bekommen, wenn Sie diese Anleitung umsetzen. Die Programme werden nicht funktionieren.

Aktualisieren Sie die Firmware Ihrer CCU! Wählen Sie „Standard“ als Logikschicht-Version aus!

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.

CUx-Daemon

Im Prinzip kann man das T-Framework ohne jegliche Zusatzsoftware auf der CCU installieren. Dabei würde jedoch system.Exec() verwendet – und das auch noch mit einem Befehl, der möglicherweise einige Zeit zur Ausführung braucht. Erfahrungsgemäß wird die CCU bei solchen Programmen nach einiger Zeit instabil und muss neu gestartet werden.

Ich empfehle daher die Installation des CuX-Daemons und die Anlage eines Systemgerätes zum Ausführen von Programmen. Ich habe das hier etwas näher beschrieben.

Für das T-Framework verwende ich einen weiteren Kanal meines CUxD-Gerätes.

Wichtig ist hier die Seriennummer. Das CUxD-EXEC-Gerät, das ich für Telegram verwenden werde, trägt die Nummer :5 am Ende.

Systemvariable anlegen

Der Versand erfolgt über eine Systemvariable, also ist der erste Schritt – natürlich  – das Anlegen einer solchen.

Es handelt sich um eine einfache Systemvariable vom Typ „Zeichenkette“, die ich – gewohnt einfallslos – Telegram nenne. Mehr gibt es hier nicht zu tun – das war’s schon.

WebUI-Programm und Versandscript

Das WebUI-Programm, das im Grunde das komplette T-Framework darstellt, sieht sehr übersichtlich aus.

Die Logik ist folgende:

Das Script wird wie üblich in das WebUI-Programm eingefügt.

! HomeMatic-Script
! TELEGRAM-FRAMEWORK
! http://www.christian-luetgens.de/homematic/telegram/telegramframework/T-Framework.htm

object o = dom.GetObject ("Telegram");
string s = o.Value();

if (s != "") {
  string s_cmd = "wget --no-check-certificate --quiet -O /dev/null \"https://api.telegram.org/bot314321353:AAFKjr29dF940b-aTchoFJ_pb6oZKxzx8Zw/sendMessage?chat_id=374629384&text=" # s.ToUTF8().UriEncode() # "\"";
  dom.GetObject("CUxD.CUX2801001:5.CMD_EXEC").State (s_cmd);
  o.State ("");
}

!  Ende des Scripts

Durch den langen String in der vierten Zeile sieht es im Editor nicht so hübsch aus, aber da meine CCU sich bei String-Verarbeitung gerne verschluckt, habe ich hier möglichst wenig davon eingebaut.

Zeilen 1 und 2

Die Systemvariable Telegram wird gesucht, in der der zu versendende Text steht.

Zeile 3

Das weitere Script wird nur ausgeführt, wenn die Systemvariable nicht leer ist – eigentlich kümmert sich das WebUI-Programm bereits darum, aber sicher ist sicher.

Zeile 4

Die Befehlszeile wird zusammengesetzt:

  • wget – das aufzurufende Programm
  • --no-check-certificate – die Telegram-API wird verschlüsselt angesprochen, aber das reduzierte Betriebssystem der CCU hat keine Möglichkeit, die entsprechenden Zertifikate zu prüfen, also prüft es nicht
  • --quiet – wget gibt normalerweise Informationen während des Downloads der URL aus; mit --quiet nicht
  • -O /dev/null – wget ist eigentlich ein Tool, um Webseiten herunterzuladen und zu speichern; mit -O kann man die Ausgabedatei festlegen, und /dev/null ist das digitale Nirvana eines Linux-Systems
  • https… – die URL, wobei an den passenden Stellen HTTP-Token (bei mir 314321353:AAFKjr29dF940b-aTchoFJ_pb6oZKxzx8Zw) und Chat-ID (bei mir 374629384) eingesetzt werden müssen
  • s.ToUTF8().UriEncode() – der Text, codiert für die Übergabe an wget als URL

Über .State() können häufig keine langen, komplexen Zeichenketten direkt übergeben werden – die Fehlerprüfung in der WebUI meldet Syntaxfehler. Mit Umweg über einen String funktioniert es dann.

Zeile 5

Der Befehl wird dem CUx-Daemon zur Ausführung übergeben, das Ergebnis ist mir egal – wird schon klappen.

Der genaue Name des virtuellen Gerätes wird in der Geräteliste der CCU angezeigt. Wahrscheinlich wird hier nur die :5 gegebenenfalls abweichen – aber schauen Sie im Zweifelsfall lieber noch einmal nach.

Zeile 6

Die Systemvariable wird geleert, damit nicht beim Neustart der CCU oder ähnlichem alte Nachrichten rausgehen.

Sonderzeichen und Umlaute

Bis vor kurzem waren die verfügbaren Funktionen zur String-Bearbeitung in der CCU-Scriptsprache extrem begrenzt. Mein originales kurzes Versandscript hatte daher Probleme mit Sonderzeichen und Umlauten, die manuell gesucht und ersetzt werden mussten.

Das ist nun vorbei – die Umwandlung über .ToUTF8().UriEncode() sorgt dafür, dass von Umlauten bis Zeilenumbrüchen alles sauber ankommt. Dementsprechend entfällt auch das zweite Versandscript, das es bisher auf dieser Seite gab und das sich um die Ersetzungen gekümmert hatte.

Die doppelte Umwandlung und Codierung liegt wieder in Eigenheiten der WebUI begründet. Je nachdem, auf welchem Weg Umlaute in Zeichenketten gelangen, sind sie unterschiedlich codiert. Daher „normalisiere“ ich den String erst zu UTF-8 und wandle ihn dann in RFC-konforme Zeichen für die URL um. Das scheint am zuverlässigsten zu klappen.

Falls einzelne Telegram-Nachrichten nicht gesendet werden, wäre das eine Stelle, an der man nachschauen kann.

Manchmal träume ich nachts von einer Welt, in der man sich nicht mit unterschiedlichen Zeichensätzen herumschlagen muss.

Testprogramm

Ein zweites kleines (Test-)Programm macht nichts anderes, als die Systemvariable Telegram zu setzen.

Das Programm hat keine Bedingung. Es wird ausgeführt, sobald es gespeichert wird, wenn die CCU startet oder wenn man das Programm manuell unter Status und Bedienung / Programme auslöst (siehe Die Logik von WebUI-Programmen).

Unmittelbar nach Start des Programms empfängt mein Telegram-Bot seine erste Nachricht:

Hurra – es funktioniert! Die Nachricht kommt an und die Umlaute sind korrekt codiert.

Das Testprogramm hat seine Pflicht getan und kann gleich wieder gelöscht werden.

Navigation