SSChatBot - Integration des Synology Chat Servers

Aus FHEMWiki
Zur Navigation springen Zur Suche springen

Das Modul 50_SSChatBot ist zur Zeit in Entwicklung und steht momentan nur als Download aus dem contrib (DS_Starter) zur Verfügung.

Der aktuelle Entwicklungsstand kann einfach per Download mit diesem Befehl in der FHEM Kommandozeile bezogen werden. Bitte so komplett mit den Ausführungszeichen am Anfang und Ende eingeben:

 "wget -qO ./FHEM/50_SSChatBot.pm https://svn.fhem.de/fhem/trunk/fhem/contrib/DS_Starter/50_SSChatBot.pm"

Danach FHEM restarten.


Zweckbeschreibung

Mit diesem Modul erfolgt die Integration des Synology Chat Servers in FHEM. Dadurch ist es möglich, Nachrichten zwischen FHEM und Synology Chat Server auszutauschen. Der Synology Chat Server arbeitet ohne eine public Cloud. Dieser Dienst ist vielmehr für den Synology Server Besitzer ein Teil einer private Cloud Lösung.



Definition eines ChatBot-Devices

Die Definition ist einfach:

define <Name> SSChatBot <Adresse Synology Server> [Port] [Protokoll]

Die Angaben Port und Protokoll sind optional, per default werden Port=5000 und Protokoll=http verwendet.

  • Port: Port der Synology Diskstation (default 5000)
  • Protokoll: Protokoll für Messages Richting Chat-Server, http oder https (default http)

Beispiel mit HTTPS:

define SynChatBot SSChatBot 192.168.2.10 5001 https

Bei der Definition wird sowohl ein SSChaBot Device als auch ein extra FHEMWEB Device zum Nachrichtenempfang automatisiert im Raum "Chat" angelegt. Der Port des FHEMWEB Devices wird automatisch ermittelt mit Startport 8082. Ist dieser Port belegt, werden die Ports in aufsteigender Reihenfolge auf eine eventuelle Belegung durch ein FHEMWEB Device geprüft und der nächste freie Port wird dem neuen Device zugewiesen.

Die Chatintegration unterscheidet zwischen "Eingehende Nachrichten" (FHEM -> Chat) und "Ausgehende Nachrichten" (Chat -> FHEM). Das SSChatBot Device konfiguriert beide Übermittlungstypen wie nachfolgend beschrieben.


Aktivierung eingehende Nachrichten (FHEM -> Chat)

Für den Betrieb des ChatBots wird ein Bot-Token benötigt. Dieser Token wird über die benutzerdefinierte Einbindungsfunktionen erstellt bzw. kann darüber auch verändert werden. Klicken Sie dazu auf das Symbol Profilfoto oben rechts in der aufgerufenen Synology Chat-Applikation und wählen Sie Einbindung. Wählen sie dann Bots und erstellen einen neuen Bot oder verändern einen vorhandenen Bot.

In Einbindungseinstellungen:

  • "Aus Botliste ausblenden" deaktivieren
  • einen Namen und optionale Beschreibung vergeben
  • den Token aus dem Feld "Token" herauskopieren

Wichtig: vor den nächsten Schritten ist der neue Bot zu speichern um ihn zu aktivieren. Andernfalls kommt die Meldung "bot is not legal" im erstellten SSChatBot Device.

Der Token wird nun in das neu definierten SSChatBot-Device eingefügt. In diesem Beispiel wäre es:

set SynChatBot botToken U6FOMH9IgT22ECJceaIW0fNwEi7VfqWQFPMgJQUJ6vpaGoWZ1SJkOGP7zlVIscCp

War die Speicherung erfolgreich, kann mit:

get SynChatBot storedToken

der gespeicherte Token jederzeit angezeigt werden.



War die Definition erfolgreich, werden die im Synology Chat Server verfügbaren User abgefragt und zur weiteren Verwendung gespeichert. Konnte diese Abfrage fehlerfrei ausgeführt werden, springt der state des Device auf "active".

Sollten keine User in diesem Attribut erscheinen, bitte auf der Synology kontrollieren ob die gewünschten User die Berechtigung für die Chat-Anwendung besitzen.



Aktivierung ausgehende Nachrichten (Chat -> FHEM)

Für Nachrichten des Chat in Richtung FHEM muß in der Chat-Applikation das Feld Ausgehende URL gefüllt werden.

Klicken Sie dazu auf das Symbol Profilfoto oben rechts in der aufgerufenen Synology Chat-Applikation und wählen Sie Einbindung. Wählen sie dann im Menü Bots den bereits den für eingehende Nachrichten verwendeten Bot aus.

In das Feld Ausgehende URL wird nun der Wert des Internals OUTDEF des erstellten SSChatBot Devices hineinkopiert. Zum Beispiel könnte der String so aussehen:

 http://fhemtest.myds.me:8086/sschat/outchat?botname=SynChatBot&fwcsrf=5de17731



Set-Optionen


botToken
speichert den Token für den Zugriff auf den Chat als Bot
listSendqueue
zeigt die noch an den Chat zu übertragenden Nachrichten (sofern vorhanden)
sendItem
sendet einen Nachricht an einen oder mehrere Chatempfänger
purgeSendqueue < -all- | index >
löscht alle Einträge der Sendqueue (-all-), oder den ausgewählten Eintrag mit "index". Die Einträge in der Sendqueue kann man sich vorher mit "set listSendqueue" ansehen um den gewünschten Index zu finden.



verschiedene Arten Nachrichten an Chatempfänger senden


Mit dem Kommando:

set <Name> sendItem <Item>

werden Nachrichten an den oder die Chatempfänger gesendet. Je nach dem zu versendenden Inhalt variiert der Inhalt von <Item>. Nachfolgend sind die verschiedenen Varianten, wie <Item> gefüllt werden kann, dargestellt.


  • die einfachste Möglichkeit eine Textnachricht [an user1] zu senden
First line of message to post.\nAlso you can have a second line of message. [users="user1"]


  • eine Textnachricht [an user1] mit dem text-Tag senden
text="First line of message to post.\nAlso you can have a second line of message." [users="user1"]


  • einen Link [an user1] senden
text="<https://www.synology.com>" [users="user1"]


  • eine andere Variante einen Link [an user1 und user2] senden
text="Check this!! <https://www.synology.com|Click here> for details!" [users="user1,user2"]


  • eine Datei [an user1 und user2] senden. Die Datei muss über die angegebene URL (fileUrl) für den Synology Chat Server zugreifbar sein. Die maximale Größe zum Hochladen von Dateien beträgt 32 MB.
text="a fun image" fileUrl="http://imgur.com/xxxxx" [users="user1,user2"]


Die Empfänger [users=] sind optional falls der/die Empfänger im Attribut "defaultPeer" bereits angegeben wurden. Ein im "sendItem" angegebener Empfänger hat aber immer Vorrang vor einem eventuell gesetzem Attribut "defaultPeer".

Die zu sendenden Nachrichten werden zunächst in eine interne Sendqueue gestellt und sofort versendet, sofern der Bot die Nachricht übermitteln konnte. Bei auftretenden Fehlern wird der Sendvorgang in Abständen wiederholt, wobei der Abstand zwischen den Sendeversuchen mit der Anzahl der erfolglosen Versuche ansteigt.


Zu Hinweisen bezüglich des Textversands siehe auch Beschränkungen und Known Bugs.


Beispiel für den Dateiversand:

Es soll eine Kameraaufnahme an die im Attribut "defaultPeer" angegebenen Empfänger gesendet werden. Dadurch kann auf die Angabe der Empfänger im Tag "users=" verzichtet werden.

 set <Name> sendItem text="letzte Aufnahme von Kamera" fileUrl="http://sdcam.myds.me:8081/surveillance/Hauseingang/20191124AM/Hauseingang-20191124-103741-1574588261.mp4"



Get-Optionen


chatUserlist
erstellt eine Liste der für den Bot sichtbaren Usern. Sollten keine User gelistet werden, muss den Usern auf der Synology die Berechtigung für die Chat-Anwendung zugewiesen werden.
chatChannellist
erstellt eine Liste der für den Bot sichtbaren Channels
storedToken
zeigt den gespeicherten Token an
versionNotes
listet wesentliche Versionsänderungen auf


Synology Chat User auflisten

Eine Liste der verfügbaren Chat User wird mit

get <Name> chatUserlist

abgerufen. Die erscheinenden Usernamen können als Default-Empfänger im Attribut "defaultPeer" gespeichert werden. Eine Mehrfachauswahl ist möglich.



Attribute


defaultPeer
ein oder mehrere (default) Empfänger für Nachrichten. Kann mit dem "users=" Tag im Befehl "sendItem" übersteuert werden.
showTokenInLog
wenn gesetzt wird im Log mit verbose 4/5 der übermittelt Bot-Token angezeigt. (default: 0)
httptimeout
stellt den Verbindungstimeout zum Chatserver ein (default 4 Sekunden)



Nachrichten und Befehle aus dem Chat an FHEM senden


empfangene Chat Daten

Aus dem Synology Chat können Nachrichten oder Befehle an FHEM gesendet werden. Dazu ist zunächst der Bot, mit kommuniziert werden soll, dem persönlichen Chat hinzuzufügen. Im linken Menü bei Bots auf das + klicken, den relevanten Bot auswählen und mit Klick auf Eingabe fügt den Bot hinzu.

Hat man den Bot-Kanal betreten, können Textnachrichten oder Befehle an den Bot gesendet werden. Die empfangenen Daten werden im SSChatBot Device in verschiedenen, mit dem Präfix rec beginnenden Readings dargestellt. Die Inhalte der Readings sind von der empfangenen Nachricht abhängig.


Weiterhin können Set- und Get-Befehle an FHEM gesendet, sowie Perl-Code in FHEM ausgeführt werden. Die Rückgabe-Daten der ausgeführten Befehle werden an den Synology Chat übermittelt.

Diese Möglichkeiten sind zuvor im Synology Chat als sogenannte Slash-Befehle zu konfigurien.



Slash-Befehle im Synology Chat konfigurieren


Slash-Befehl für "set" konfigurieren

Klicken Sie dazu auf das Symbol Profilfoto oben rechts in der aufgerufenen Synology Chat-Applikation und wählen Sie Einbindung. Wählen sie dann Slash-Befehl und erstellen einen neuen Schrägstrich-Befehl oder verändern einen vorhandenen Befehl.

In dem Beispiel werden die Felder für set-Befehle konfiguriert:

  • Namen anpassen : ein Name für den neuen Slash-Befehl
  • Befehl : der Befehl, z.B. "set". Zur Verwendung mit FHEM sind zur Zeit set..., get... und code... möglich. Zur Unterscheidung verschiedener Ziele ist z.B. set, set_test, set_prod, get, get_prod, usw. möglich. Der Befehl muß mit set, get oder code beginnen damit er dementsprechend erkannt wird.
  • Anfrage-URL : hier wird wieder der Inhalt des Internals OUTDEF hineinkopiert
  • Befehls-Anweisungen : hier gibt man einen ergänzenden Text ein, der als Ausfüllhilfe bei der Eingabe eines "/" angezeigt werden soll.
    Zum Beispiel wird "<Device> <Befehl>" später bei Eingabe von "/" als "/set <Device> <Befehl> [Beschreibung]" angezeigt.
  • Beschreibung : ergänzende Beschreibung zum Befehl, z.B. "um einen Set-Befehl an FHEM zu senden".
    Dadurch wird später bei Eingabe eines "/" der Eintrag als "/set <Device> <Befehl> um einen Set-Befehl an FHEM zu senden" in der Befehlsliste angezeigt.
Befehls-Anweisungen und Beschreibung
empfangener Befehl und Rückgabewert







Ist die Konfiguration abgespeichert, kann nun durch Eingabe von:

/set <Device> <Befehl>

eine Set-Anweisung an FHEM ausgeführt werden. Zum Beispiel wird mit:

/set CamHE1 snap
Rückgabewert im Chat

ein Schnappschuss mit der Kamera CamHE1 ausgeführt. Die Kommunikation mit dem Chat zeigen die Readings im SSChatBot Device. Der von FHEM gemeldete Ausführungsstatus des Befehls wird an den Chat zurück gesendet.

Entsprechendes gilt ebenfalls für die Konfiguration der get- und code-Befehle.



Befehle aus dem Chat an FHEM senden


Nachfolgend dargestellte Syntax ausgehender Befehle wird vom SSChatBot Device akzeptiert. Die unterschiedlichen Varianten dienen dazu, Slash-Befehle für verschiedene Ziele (Testsysteme, Produktivsystem) definieren zu können.

Set-Befehle

Alle diese Varianten werden in FHEM als "set" ausgeführt.

  • /set <Device> <Befehl>
  • /set_test <Device> <Befehl>
  • /setProd <Device> <Befehl>


Get-Befehle

Alle diese Varianten werden in FHEM als "get" ausgeführt.

  • /get <Device> <Befehl>
  • /get_test <Device> <Befehl>
  • /getProd <Device> <Befehl>


Code-Befehle

In FHEM auszuführender Perl-Code muß in {} eingeschlossen werden.

  • /code {return "das ist ein Return Test";}
  • /code_test {my $ret = "das ist ein Return Test"; return $ret;}
  • /codeProd {function()}



Beschränkungen und Known Bugs


Die Textnachrichten an den Chat dürfen bestimmte Zeichen nicht enthalten und werden entweder vor dem Versand ersetzt oder eliminiert.

  • # -> Hashtags werden entfernt
  • = -> sollen Gleichheitszeichen im Text übermittelt werden, muss die Form mit text-Tag gewählt werden, z.B. text="etwas ist = etwas" .
  • <blank>H -> wird ein großes "H" von einem Leerzeichen angeführt, verursacht das einen Fehler im Chat. In diesem Fall wird " H" durch " h" ersetzt. (Synology Chat Bug)
  • & -> ist im Text nicht erlaubt und wird entfernt



Links

Forumthread zu diesem Modul: https://forum.fhem.de/index.php/topic,105714.0.html
Synology KnowldgeBase: https://www.synology.com/de-de/knowledgebase/DSM/help/Chat/chat_desc