Motivation
Die nachfolgende Anleitung soll dazu dienen, Push-Nachrichten, die durch unterschiedliche WebUI-Programme bzw. -Skripte erzeugt wurden, durch ein zentrales Programm wahlweise mit den Push-Diensten
Pushover (iOS, Android sowie als Desktop-Variante für Safari, Chrome oder Firefox),
Pushsafer (iOS, Android, Windows Mobile, Windows Desktop sowie Chrome, Firefox) und/oder
Telegram (nahezu alle aktuellen OS)
Prowl (iOS, Mac OS X sowie als Desktop-Variante für Chrome oder Firefox, zudem als Growl für Windows und Snarl verfügbar),
Pushalot (Windows Phone bzw. Mobile, Windows Desktop ab Version 8),
zu verschicken. Im Folgenden werden das zentrale Push-Nachrichten-Programm kurz als zPNP und die darin enthaltenen zentralen Push-Nachrichten-Skripte als zPNS-Po, zPNS-Pl, zPNS-Pa, zPNS-Ps und zPNS-Tg bezeichnet.
Prowl und Pushalot werden aktuell nicht mehr gepflegt.
Warum das Ganze? Nun, hier mal eine Auflistung der Vorteile gegenüber dem Aufrufen der Push-Dienste in einzelnen Programmen und Skripten.
- Die Änderung von API-Keys muss nur noch an einer einzigen Stelle vorgenommen werden.
- Übersetzung von Umlauten und Leerzeichen in den zPNS-xx in UTF-8.
- Deutliche Vereinfachung der das zPNP aufrufenden Skripte mit entsprechend vereinheitlichter Struktur.
- Zentrale Nutzerverwaltung für den Fall, dass Push-Nachrichten an mehrere Empfänger verschickt werden sollen.
- Kontrolle darüber, ab welcher Prio weitere Empfänger Push-Nachrichten empfangen sollen.
- Möglichkeit zur Auswahl einzelner Push-Dienste für unterschiedliche Ereignisse.
- Möglichkeit zur generellen Deaktivierung von Push-Nachrichten mit einer Priorität < 2.
- Möglichkeit zur Unterbindung identischer Push-Nachrichten innerhalb eines definierbaren Zeitfensters (nicht bei Priorität 2).
- Möglichkeit zum Bilderversand mit Pushover, Pushsafer und Telegram.
- Achtung: Ab Version 2.1 der zPNS-xx ist ein WebUI ab der Version 2.29.22 erforderlich!
- Bitte auf alle Fälle vermeiden, den Inhalt von Systemvariablen auf der WebUI-Startseite anzuzeigen, wenn diese HTML-Tags enthalten.
- Wer Bedenken hinsichtlich der Verwendung von Leerzeichen, Umlauten oder Sonderzeichen in Systemvariablen-Namen hat, der sollte die Namen entsprechend ändern. Auf meiner CCU hatte ich damit in den zurückliegenden Jahren noch nie irgendwelche Probleme. Es kann aber natürlich z.B. diverse Addons für die CCU geben, die damit Probleme haben. Keine Probleme gab es bisher mit den folgenden Addons: SSH-keydir, Programmedrucken CCU2, XML-API und CUx-Deamon.
- Systemvariablen, die nicht benutzt werden, sollten in WebUI auch nicht angelegt sein.
Voraussetzungen
Zusatzsoftware
Auf der CCU muss CUxD installiert und das Gerät "CUxD.CUX2801001:1.CMD_EXEC" eingerichtet sein. Hier eine Kurzanleitung zur Einrichtung des CUxD-Geräts:
- Unter CUxD-Gerätetyp das Gerät "(28) System-Exec" auswählen und den Rest am besten unverändert lassen (Seriennummer: 1, etc.).
- Anschließend auf "Gerät auf CCU erzeugen!" klicken.
- Danach in WebUI in den Posteingang für neue Geräte gehen und den neuen Gerätetyp bestätigen.
- Zur Sicherheit CCU neu booten.
Das zPNP
Das zPNP selbst ist sehr trivial. Bei mir enthält es im "Wenn"-Zweig lediglich eine Abfrage über den Status der CCU. Diese Abfrage kann man theoretisch aber auch weglassen. Grundsätzlich empfehle ich jedoch, kein Programm oder besser noch keinen Programmzweig auf der CCU ohne Bedingung zu erstellen, weil dieses dann bei jedem Neustart der CCU ausgeführt wird.
Der Name des zPNP ("CCU PRG Push-Nachrichten") ist sehr wichtig, weil er in den aufrufenden Skripten verwendet wird. Natürlich kann dieser auch individuell gewählt werden. Aber dazu später mehr. Die von mir gewählte Nomenklatur basiert auf der Einrichtung meiner eigenen CCU. Und dort habe ich z.B. sämtlichen Programmen den Zusatz "PRG", sämtlichen Systemvariablen den Zusatz "SV" und sämtlichen virtuellen Schaltern den Zusatz "VT" verpasst. Somit kann ich einem Gerät und einer dazu gehörenden Systemvariablen ansonsten identische Namen geben. Aber dies nur am Rand.
Unter "Aktivität" sind die gewünschten zPNS-xx sowie ein kleines, aber zwingend erforderliches Skript zum Setzen der Systemvariablen "CCU SV Push Text Ref" einzufügen.
Systemvariablen
Seit Version 2.0 der zPNS-xx werden die benötigten Systemvariablen automatisch erzeugt, sofern nicht vorhanden. Die Namen der Systemvariablen können in den zPNS-xx nach eigenen Wünschen angepasst werden. Der Einfachheit halber gehe ich von den im nachfolgenden Code-Block des zPNS-xx verwendeten Namen aus.
Code: Alles auswählen
! +++++ Namen der zwingend benötigten Systemvariablen +++++
string svPushText = "CCU SV Push Text"; ! Text der aktuell zu übertragenden Push-Nachricht, Voreinstellung: "CCU SV Push Text"
string svPushTextRef = "CCU SV Push Text Ref"; ! Text der vorherigen Push-Nachricht als Referenz, Voreinstellung: "CCU SV Push Text Ref"
! +++++ Namen der optionalen Systemvariablen (auf "" setzen, wenn nicht benötigt) +++++
string svPushPrio = "CCU SV Push Prio"; ! Prioritäten der Push-Nachrichten, Voreinstellung: "CCU SV Push Prio"
string svPushService = "CCU SV Push Dienst"; ! Push-Dienste, Voreinstellung: "CCU SV Push Dienst"
string svPushImage = ""; ! Link auf ein anzufügendes Bild (z.B. "CCU SV Push Bild"), Voreinstellung: ""
Zwingend erforderlich für den Betrieb des zPNPs sind die beiden Systemvariablen "CCU SV Push Text" und "CCU SV Push Text Ref". "CCU SV Push Text" enthält den aktuell zu übertragenden Textinhalt der Push-Nachricht. "CCU SV Push Test Ref" dient als Referenz und ist wichtig für die Möglichkeit zur zeitweisen Sperrung identischer Push-Nachrichten. Auch dazu später mehr.
Um das zPNP mit mehreren Push-Diensten betreiben und möglichst variabel steuern zu können, empfiehlt sich die zusätzliche Einrichtung der Systemvariablen "CCU SV Push Prio" und "CCU SV Push Dienst".
Damit die Systemvariablen nun erzeugt werden, muss das zPNP einmal per Klick auf den Start-Button unter "Status und Bedienung | Programme" ausgeführt werden.
Die Systemvariable "CCU SV Push Prio" dient zum Setzen der Priorität der Push-Nachrichten. Sowohl Prowl als auch Pushover nutzen Prioritäten von -2 bis 2. Allerdings ist die Bedeutung bei den beiden Diensten etwas abweichend. Daher kann es sein, dass sich bei gleichzeitiger Nutzung dieser Push-Dienste ein unterschiedliches Verhalten ergibt. Pushalot, Pushsafer und Telegram arbeiten eigentlich nicht mit Prioritäten. Pushalot erlaubt aber stattdessen eine Beeinflussung über die Parameter "IsImportant" und "IsSilent". Bei Pushsafer kann man verschiedene Sounds, Icons, Titel und Vibrationen setzen. Bei Telegram lassen sich den Prioritäten entsprechende Bots definieren, die dann mit unterschiedlichen Sounds und/oder Icons auf Push-Nachrichten hinweisen. Zur einheitlichen Nutzung des zPNPs habe ich mich entschieden, auch für Pushalot, Pushsafer und Telegram die obigen Prioritäten zu verwenden.
Für Pushalot werden "IsImportant" sowie "IsSilent" entsprechend der nachfolgenden Regel angepasst:
Prio -2, -1: IsImportant=False, IsSilent=True
Prio 0: IsImportant=True, IsSilent=True
Prio 1, 2: IsImportant=True, IsSilent=False
Bei Pushsaver habe ich mich für folgende Werte für den Sound (s), die Vibration (v) und das Icon (i) entschieden:
Prio -2: s=0, v=1, i=4
Prio -1, 0: v=1, i=4
Prio 1: v=1, i=5
Prio 2: v=1, i=6
Für Telegram sollten gemäß den Erläuterungen in einem der nachfolgenden Postings entsprechende Bots angelegt werden. Zudem wird bei Prio -2 die Ausgabe von Tönen mit dem Parameter "disable_notification=1" unterbunden.
"CCU SV Push Dienst" erlaubt zum einen, gezielt einen bestimmten Push-Dienst in einem das zPNP aufrufenden Programm bzw. Skript auswählen zu können. Zum anderen kann die Systemvariable auch mit einer anderen App, wie z.B. pocketControl, auf "aus" gesetzt werden, um das Versenden von Push-Nachrichten generell zu unterdrücken. Hierbei gilt aber zu beachten, dass Push-Nachrichten der Priorität 2 (Alarm) niemals unterbunden werden. Mehr dazu in einem nachfolgenden Posting zum Aufruf des zPNP. "CCU SV Push Dienst" wird automatisch mit den Namen der Pushdienste in der Reihenfolge der zPNS-xx gemäß zPNP gefüllt, wobei die beiden ersten Einträge für "aus" und "alle" reserviert sind. Es spielt also keine Rolle, wie die zPNS-xx sortiert sind. Selbst später kann die Sortierung geändert werden, ohne dass es eine Einschränkung in der Funktionalität gibt. Das fangen die zPNS-xx automatisch auf.
Für Pushover und Pushsafer können noch jeweils zwei weitere Systemvariablen eingerichtet werden. "CCU SV Pushover Sound" bzw. "CCU SV Pushsafer Sound" erlaubt es, zwischen 15 (Pushover) bzw. 27 (Pushsafer) verschiedenen Sounds bei der Übertragung von Pushover- bzw. Pushsafer-Nachrichten zu wählen. Bei Prowl existieren lediglich fünf feste Benachrichtigungssounds, die direkt von der gesetzten Priorität abhängen und nur innerhalb der App definiert werden können. Pushalot bietet derzeit keine Auswahl von Sounds. Telegram ermöglicht, wie gesagt, die Verwendung unterschiedlicher Sounds in Abhängigkeit von den Bots oder auch von definierten Gruppen.
Mit den Systemvariablen "CCU SV Pushover Gerät" bzw. "CCU SV Pushsafer Gerät" hat man zudem die Möglichkeit, Pushover- bzw. Pushsafer-Nachrichten gezielt an ein unter pushover.net bzw. in der Pushsafer App definiertes Gerät (Device) zu senden.
Die Systemvariable "CCU SV Pushover Titel" erlaubt die Vergabe eine Titels für Pushover-Nachrichten.
Versand von Bildern
Seit Version 3.0 können mit Pushover, Pushsafer und Telegram neben Texten auch Bilder direkt über die CCU versendet werden. Dazu dient die optionale Systemvariable "CCU SV Push Bild", die wie die obigen Systemvariablen automatisch angelegt wird, wenn sie beim Aufruf des zPNP bzw. des zPNS-Po, zPNS-Ps oder zPNS-Tg noch nicht angelegt war. Pushalot und Prowl eignen sich nicht zum Bildversand. Seit Version 2.2 werden die entsprechenden zPNS-xx nicht mehr von mir gepflegt.
In die Systemvariable "CCU SV Push Bild" wird mit dem aufrufenden Skript der Pfad inkl. Namen der zu übertragenden Bilddatei eingetragen. Wurde zum Beispiel eine Datei Bild.jpg in das tmp-Verzeichnis der CCU gespeichert, dann muss"CCU SV Push Bild" auf "/tmp/Bild.jpg" gesetzt werden. Es ist aber auch möglich, direkt Pfade auf eine Webcam oder dergleichen zu setzen.
Die zPNS-xx
Kommen wir zum wesentlichen Bestandteil des zPNP, den zPNS-xx. Es ist möglich, bis zu 100 User pro Push-Dienst zu definieren. Dazu gibt es eine so genannte Master-Liste, die die durch Leerzeichen getrennten Keys für jeden User enthalten. Jedem Key ist dabei ein Identifyer "xx|" vorangetellt. Wenn man also nur einen User hat, trägt man jeweils nur einen Key "01|+++key1+++" ein. Hat man zwei User, trägt man zwei Keys "01|+++key1+++ 02|+++++key2+++++" ein, die durch ein Leerzeichen getrennt sind. Bei drei Usern sind es drei Keys und so weiter. Achtung, es darf nur ein einziges Leezeichen zwischen den Keys eingetragen sein. Hier mal ein Beispiel für Pushover
Hier mal ein Beispiel für Pushover mit drei Usern:
Code: Alles auswählen
string keyList = "01|+++key1+++ 02|+++++key2+++++ 03|++key3++"; ! API-Basisschlüssel
string HMinfoList = "01|+++++key1+++++ 02|+++++key2+++++ 03|+++++key3+++++"; ! API-Schlüssel für Info-Meldungen
string HMwarnungList = ""; ! optionale API-Schlüssel für Warnmeldungen
string HMalarmList = ""; ! optionale API-Schlüssel für Alarmmeldungen
string prioMinList = "02|0 03|-1"; ! Prioritäten, ab der die User Nachrichten erhalten sollen
Code: Alles auswählen
string keyList = "02|+++++key2+++++ 03|++key3++ 01|+++key1+++ "; ! API-Basisschlüssel
string HMinfoList = "01|+++++key1+++++ 03|+++key3+++ 02|+++++key2+++++"; ! API-Schlüssel für Info-Meldungen
string HMwarnungList = "02|++key2++"; ! optionale API-Schlüssel für Warnmeldungen
string HMalarmList = "04|+++++++++++key4|+++++++++++"; ! optionale API-Schlüssel für Alarmmeldungen
string prioMinList = "03|0 04|-1"; ! Prioritäten, ab der die User Nachrichten erhalten sollen
Mit prioMinList definiert man die Prioritäten, ab denen die einzelnen User Push-Nachrichten erhalten sollen. Wird für einen User kein Wert definiert, erhält er automatisch sämtlich Push-Nachrigen aller Prioritäten. Tipp: Last hier den Identifyer "01|" weg, da der erste User am besten immer Push-Nachrichten aller Prioritäten empfangen können sollte. Es ist aber trotzdem möglich, ihn auf Wunsch zu definieren. Mit "01|0" würde User1 z.B. nur Push-Nachrichten ab der Priorität 0 erhalten.
Pushover - zPNS-Po
Pushsafer - zPNS-Ps
Telegram - zPNS-Tg
Pushalot - zPNS-Pa (wird seit Version 2.2 nicht mehr weitergeführt)
Prowl - zPNS-Pl (wird seit Version 2.2 nicht mehr weitergeführt)
Abschlussskript zum Setzen der Push-Nachrichten-Referenz (erforderlich)
Die fünf Push-Dienste können einzeln oder in beliebiger Kombination genutzt werden. Sobald ein API-Schlüssel eingegeben wurde, wird der entsprechende Push-Dienst vorbehaltlich des Wertes der Systemvariablen "CCU SV Push Dienst" genutzt. Wird "CCU SV Push Dienst" nicht verwendet, gehen die eingebundenen zPNS-xx automatisch von ihrer Verwendung aus (default = 1 -> alle).
Für Pushover, Pushalot und Telegram können überdies noch verschiedene App- bzw. Bot-Tokens zur Unterscheidung von normalen Informationen (Prio -2, -1, 0), Warnungen (Prio 1) und Alarmmeldungen (Prio 2) eingerichtet und verwendet werden. Im Gegensatz zu Pushover ist bei Pushalot die Verwendung der App-Tokens kein normaler User-Key mehr erforderlich. Telegram bedingt die Verwendung von Bots, so dass hier nur einfach weitere API-Schlüssel für die zusätzlichen Bots hinzu kommen. Mehr dazu in einem der nachfolgenden Postings.
Updates der zPNS-xx
Wenn nicht explizit anders von mir erwähnt, zum Updaten am besten einfach alles unterhalb von
Code: Alles auswählen
! #####################################################################
! ##### ab hier bitte keine weiteren Einstellungen mehr vornehmen #####
! #####################################################################
HTML-Tags
An dieser Stelle möchte ich mich sehr beim User SMA bedanken, der mir einige wichtige Impulse zur Lösung des Problems gegeben hat.
Pushover und Telegram bieten die Möglichkeit zur Verwendung so genannter HTML-Tags. Damit lassen sich Textteile von Push-Nachrichten in der App z.B. farbig oder fett hervorheben. Ein Problem ist jedoch, dass Prowl, Pushalot und Pushsafer mit diesen HTML-Tags nichts anfangen können und Telegram den HTML-Tag "<font color=...>...</font>" nicht versteht. Pushsafer verwendet zum Hervorheben von Texten statt HTML- sogenannte BBCode-Tags. Die einzelnen zPNS-xx wandeln jedoch etwaig verwendete HTML-Color-Tags automatisch in für sie nutzbaren Code um.
So erzeugt das zPNS-Tg aus "<font color='orange'>Dies</font> ist ein <font color='red'>Test</font>." automatisch den String "<b'>Dies</b> ist ein <b>Test</b>.", während das zPNS-Ps ihn in "Dies ist ein Test." wandelt. Das zPNS-Po lässt den String dagegen unverändert, während das zPNS-Pl und das zPNS-Pa sämtliche HTML-Tags vollständig entfernen.
Unterbindung aufeinander folgender, identischer Push-Nachrichten
Die zPNS-xx enthalten noch eine weitere Variable, über die man den Versand von Push-Nachrichten beeinflussen kann. Mit "stopRepeat" definiert man einen Zeitraum, innerhalb dem keine identischen Push-Nachrichten gesendet werden sollen. Sobald eine andere Push-Nachricht gesendet wurde, beginnt diese Sperrzeit wieder von vorne. Ich habe diese Variable eingeführt, weil ich gelegentlich mit Push-Nachrichten eines prellenden Sabotage-Kontakts eines Fenster-Drehgriffkontakts bombadiert wurde. Auch kann man damit recht gut Push-Nachrichten über das zu häufige Betätigen der Haustürklingel oder dergleichen unterbinden. Standardmäßig ist "stopRepeat" auf 10 Sekunden gesetzt, kann aber auch beliebig variiert werden. Will man zum Beispiel die Funktion der zPNS-xx testen, sollte "stopRepeat" auf 0 oder einen entsprechend geringen Wert gesetzt werden.
Wichtig: Damit das Unterbinden funktioniert, muss am Ende des zPNP das oben erwähnte, kleine Skript zum Setzen der Systemvariablen "CCU SV Push Text Ref" angefügt werden.
Übrigens können für jedes zPNS-xx unabhängig voneinander unterschiedliche Sperrzeiten definiert werden. Dies nur zur Info, falls es mal jemand benötigen sollte.
Im nächsten Posting zeige ich Euch dann ein einfaches Beispiel zum Aufruf des zPNP in einem Skript.
Beispiele für das zPNP aufrufende Skripte
- Servicemeldungen auf Grundlage des Allinclusive-Skripts von Alchy.
- Skripte für Strom-, Gas- und Wasserzähler.
- Zentrales Programm und Skript zur Steuerung von Beschattungsgeräten (Rollladen, Markisen, Raffstore, Jalousien, etc.).
- Alarmmeldung bei Auslösen eines Rauchmelders.
- Meldung unverschlossener Fenster und Türen bei Abwesenheit.
- Meldungen von Briefkasten-Einwürfen und der Leerung des Briefkastens.
- Ausschalten von Verbrauchern bei Abwesenheit.
- Sturmwarnungen.
- Meldung einer fertigen Waschmaschine und eines fertigen Trockners mittels HM-ES-PMSw1-Pl.
- Meldung über einen offenen Tagesriegel (analog auch auf Fenster und Türen anwendbar).
Thorsten
Versionshistorie
- Version 1.0
- Komplette Überarbeitung des bishirgen zPNS.
- Einbindung der drei Push-Dienste Pushover, Prowl und Pushalot.
- Version 1.1
- Überarbeitung des Prowl-Aufrufs
- Entfernung der Möglichkeit zum Zurücksetzen bestimmter Systemvariablen (push_reset)
- Version 1.2
- Hinzufügung von Telegram.
- Aufteilung des zPNS in einzelne zPNS-xx (zPNS-Po, zPNS-Pl, zPNs-Pa, zPNS-Tg).
- Umbenennung der Systemvariablen "CCU SV Push-Dienst" in "CCU SV Push Dienst".
- Umbenennung der Systemvariablen "CCU SV Push Sound" in "CCU SV Push Pushover-Sound".
- Version 1.3
- Neues Abschlussskript für das Setzen von "CCU SV Push Text Ref".
- Reihenfolge und Anzahl der zPNS-xx innerhalb des zPNP nun beliebig.
- Umbenennung der Systemvariablen "CCU SV Push Pushover-Sound" in "CCU SV Pushover Sound".
- Möglichkeit zur Einbindung von Devices in Pushover und Einführung der optionalen Systemvariablen "CCU SV Pushover Gerät".
- zPNS-xx 1.3.1: Deklaration der Variablen prio als Integer statt als String.
- Version 1.4
- Senden von Push-Nachrichten der Prio 2 unabhängig von der Systemvariablen "CCU SV Push-Dienst".
- Vermeidung der Unterdrückung identischer, aufeinander folgender Push-Nachrichten im Falle von Prio = 2.
- Unterdückung von Sounds für Telegram im Falle von Prio = -2.
- zPNS-xx 1.4.1: %-Zeichen als UTF-8-Code hinzugefügt.
- zPNS-xx 1.4.2: Umwandlung UTF-8-Codes angepasst (Bugfix).
- zPNS-xx 1.4.2: ²- und ³-Zeichen als UTF-8-Code hinzugefügt.
- zPNS-xx 1.4.3: Einfügen von ".ToInteger()" bei der Prioabfrage (Bugfix). Danke an Alchy für den Hinweis.
- zPNS-Tg 1.4.3.1: Ersetzen von "disable_notifications" durch "disable_notification" (Bugfix).
- Version 1.5
- Neue, vereinfachte User-Verwaltung für sämtliche zPNS-xx.
- Einführung von Pushsafer als neuen Push-Dienst.
- Version 1.6
- Definition einer maximalen Nachrichtenlänge zum Sicherstellen des Sendens.
- Umbenennung einiger lokaler Variablen.
- Version 2.0
- Automatische Erstellung der Systemvariablen.
- Version 2.1
- Einbindung der ".ToUTF8()"-Funktion zur Umwandlung von Sonderzeichen (erfordert mindestens WebUI 2.29.22).
- Verwendung von "dom.GetObject(ID_xxx).Get(yyy)" statt "dom.GetObject(yyy)".
- Automatisches, individuelles Umwandeln von HTML-Color-Tags in den einzelnen zPNS-xx (erfordert teilweise mindestens WebUI 2.29.22 wegen ".Replace()"-Funktion).
- zPNS-Po 2.1.2: Unterstützung von Titeln inkl. UTF-8-Codes.
- zPNS-Po 2.1.3: Automatisches Löschen von Titeln nach der Übertragung.
- Version 3.0
- Unterstützung der Bildübertragung im zPNS-Po, zPNS-Ps und zPNS-Tg
- Version 3.1/2.2
- alle zPNS-xx: Einbindung der ".UriEncode()"-Funktion zur Umwandlung von Sonderzeichen
- zPNS-Po 3.1.1: Umwandlung des Farbstrings "orange" in den Farbcode "#ffa500" für Android-Geräte