Signalbot: Unterschied zwischen den Versionen

Aus FHEMWiki
(Modulbeschreibung aktualisiert)
(Attribute und Readings ergänzt)
Zeile 54: Zeile 54:
==== reinit ====
==== reinit ====
Verbindung zum DBus wiederherstellen. Dies sollte nicht nötig sein, außer der signal-cli Service funktionierte nicht richtig und wurde korrigiert. Ich rate hier aber eher zu einem FHEM Neustart.
Verbindung zum DBus wiederherstellen. Dies sollte nicht nötig sein, außer der signal-cli Service funktionierte nicht richtig und wurde korrigiert. Ich rate hier aber eher zu einem FHEM Neustart.
=== Attribute im Detail ===
==== defaultPeer ====
Gruppe, Kontaktname oder Nummer an die '''send''' eine Nachricht schicken soll, wenn kein Empfänger mit @ oder # definiert wurde.
==== allowedPeer ====
Gruppe, Kontaktname oder Nummer auf die Signalbot reagieren soll (also bei empfangenen Nachrichten Readings aktualisiert). Aktuell ist dies nur ein '''einzelner''' Sender. ''Todo: das sollte wahrscheinlich besser eine Liste sein''
'''babblePeer'''
Gruppe, Kontaktname oder Nummer auf die Signalbot reagieren soll indem es die Nachricht an das über '''babbleDev''' (nicht zu verwechseln mit ''babbleDevice'') definierte [[Modul Babble|Babble]] Modul schickt.
==== babbleDev ====
Name des definierten Babble Device. ''Todo: das könnte Signalbot auch selber finden, da es üblicherweise wohl nur ein Modul geben sollte''
=== Readings im Detail ===
{| class="wikitable"
|contactList
|Liste der gespeicherten Kontakt im Format ''Nummer1=Kontakt1,Nummer2=Kontakt2,...''
|-
|joinedGroups
|Liste der beigetretenen Gruppen getrennt mit Leerzeichen
|-
|msgAttachment
|Attachments (Dateinamen im signal-cli repository) der zuletzt empfangenen Attachments
|-
|msgGroupName
|Gruppenname aus der zuletzt eine Nachricht empfangen wurde - leer wenn es eine persönlich Nachricht war
|-
|msgSender
|Absender der letzten Nachricht als Nummer oder wenn bekannt als Name
|-
|msgText
|Empfangenen Nachricht
|-
|msgTimestamp
|Zeitstempel der Nachricht
|-
|prevMsgAttachment
| rowspan="5" |Wie oben, nur enthalten diese Readings die Daten der zuvor empfangenen Nachricht (n-1)
|-
|prevMsgGroupName
|-
|prevMsgSender
|-
|prevMsgText
|-
|prevMsgTimestamp
|-
|sentMsg
|Zuletzt gesendete Nachricht
|-
|sentMsgRecipient
|Empfänger der zuletzt gesendeten Nachricht. Enthält zumeist den Namen aus der Empfangsbestätigung und somit bei vielen Empfängern den zuletzt bestätigten Empfang.
Dies muss nicht zwingend auf die zuletzt gesendete Nachricht (sendMsg) passen, wenn mehrere Nachrichten versendet wurden.
|-
|sentMsgTimestamp
|Zeitstempel des Empfangs oder "pending" wenn noch keine Bestätigung vorliegt
|}


== Installation ==
== Installation ==

Version vom 6. Februar 2021, 13:24 Uhr

Todo: Bisher nur Basisinformationen. Beschreibung muss noch vervollständigt werden


Signalbot
Zweck / Funktion
Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messenger Signal
Allgemein
Typ Inoffiziell
Details
Dokumentation Thema
Support (Forum) Codeschnipsel
Modulname 50_Signalbot.pm
Ersteller Adimarantis (Forum /Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Das Modul Signalbot ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst Signal aus FHEM heraus.

Beschreibung

Beschreibung in Kurzform:

Signalbot stellt eine Schnittstelle von FHEM zum Signal Messenger unter Linux zur Verfügung. Dazu wird das Tool signal-cli im DBus-Daemon Modus verwendet, welches dann letztendlich mit Signal kommuniziert.

Da sich signal-cli noch in der Entwicklung befindet (aktuelle Version 0.7.4) steht leider noch nicht die volle Funktionalität über DBus zur Verfügung, wodurch sich auch Einschränkungen für FHEM ergeben.

Aktuell unterstütze Funktionen aus FHEM:

  • -Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
  • Versenden von einem oder mehreren Attachments (Bilder)
  • Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
  • Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
  • Einschränken von Gruppen oder Kontakten auf die FHEM reagieren soll
  • Direkte Verknüpfung mit dem Babble Modul zur Interpretation von Befehlen

Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches aktuell für aktuelle Ubuntu und Raspian Distributionen getestet ist (höchstwahrscheinlich aber auch für andere Debian basierte Distributionen funktioniert)

Signalbot ist weitgehend kompatibel mit SiSi, verfolgt aber technisch ein paar andere Ansätze und stellt zusätzliche Funktionalitäten zur Verfügung:

  • Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
  • Gruppen werden grundsätzlich mit ihren Klarnamen verwendet und können auch nur mit einem vorangestellten "#" (statt "@#") gekennzeichnet werden.
  • Kontakte werden soweit möglich auch mit Klarnamen (statt +49....) unterstützt. Diese kommen aus dem internen Adressbuch und können über "setContact" definiert werden, bzw. kommen bei verlinkten Accounts aus dem Adressbuch des Hauptgeräts. Sie können aktuell leider nur über empfangene Nachrichten entschlüsselt werden, da signal-cli die entsprechende Schnittstelle (noch) nicht zur Verfügung stellt. Signalbot lernt diese aber mit der Zeit und kann sie bei Bedarf auch so abspeichern, dass sie auch nach einem FHEM Neustart wieder verfügbar sind
  • Die Möglichkeit von Telegrambot in den "send" Befehl eingebetteten Code auszuführen und damit z.B. einen SVG Plot zu erstellen und mit zu verschicken ist verfügbar. Dazu muss der Befehl in runde Klammern eingebettet werden (Beispiele folgen unten).
  • Wurde mit und für die aktuelle Version 0.7.4 von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version (1.2.0) vom Perl Modul Net::DBus benötigt
  • Wird aktuell (Jan 2021) noch gewartet (letztes Update für SiSi auf github ist aktuell von August 2018)

Funktionen im Detail

send [@<Recipient1> ... @<RecipientN>] [#<Group1> ... #<GroupN>] [&<Attachment1>; ... &<AttachmentN>] [<Text>]

  • Recipient: Nummer mit Ländervorwahl (+49....) oder Kontaktname aus dem internen Adressbuch
  • Group: Gruppenname, wie in Signal definiert im Klartext
  • Attachment: Dateiname (Pfad muss für den signal-cli user lesbar sein) oder Stream einer Bilddatei (z.B.)SVG
  • Text: Die eigentlich Textnachricht, kann Leerzeichen enthalten
  • Sofern ein Recipient, Group oder Attachment Leerzeichen enthält, den ganzen Teilstring in Anführungszeichen setzen: z.B. "@Max Mustermann"
  • Wenn ein FHEM Befehl ausgeführt werden soll, dann diesen in runde Klammern setzen z.B. &({plotAsPng('SVG_Aussentemperatur')})

refreshGroups

Fragt die List der aktuellen Gruppen ab, denen der verknüpfte Account beigetreten ist. Die Liste wird im u.a. Reading joinedGroups sichtbar gemacht.

setContact <Number> <Contactname>

Definiert einen Kontakteintrag im internen Adressbuch. Es kann beim send Befehl dann der ContactName statt der Nummer verwendet werden.

saveContacts

Speichert die interne Kontaktliste in das Reading contactList welches beim Speichern der FHEM Config in fhem.save abgelegt wird und nach einem Neustart wieder zur Verfügung steht (zur Diskussion: immer automatisch so machen wenn neue Kontakte festgelegt werden?)

reinit

Verbindung zum DBus wiederherstellen. Dies sollte nicht nötig sein, außer der signal-cli Service funktionierte nicht richtig und wurde korrigiert. Ich rate hier aber eher zu einem FHEM Neustart.

Attribute im Detail

defaultPeer

Gruppe, Kontaktname oder Nummer an die send eine Nachricht schicken soll, wenn kein Empfänger mit @ oder # definiert wurde.

allowedPeer

Gruppe, Kontaktname oder Nummer auf die Signalbot reagieren soll (also bei empfangenen Nachrichten Readings aktualisiert). Aktuell ist dies nur ein einzelner Sender. Todo: das sollte wahrscheinlich besser eine Liste sein

babblePeer

Gruppe, Kontaktname oder Nummer auf die Signalbot reagieren soll indem es die Nachricht an das über babbleDev (nicht zu verwechseln mit babbleDevice) definierte Babble Modul schickt.

babbleDev

Name des definierten Babble Device. Todo: das könnte Signalbot auch selber finden, da es üblicherweise wohl nur ein Modul geben sollte

Readings im Detail

contactList Liste der gespeicherten Kontakt im Format Nummer1=Kontakt1,Nummer2=Kontakt2,...
joinedGroups Liste der beigetretenen Gruppen getrennt mit Leerzeichen
msgAttachment Attachments (Dateinamen im signal-cli repository) der zuletzt empfangenen Attachments
msgGroupName Gruppenname aus der zuletzt eine Nachricht empfangen wurde - leer wenn es eine persönlich Nachricht war
msgSender Absender der letzten Nachricht als Nummer oder wenn bekannt als Name
msgText Empfangenen Nachricht
msgTimestamp Zeitstempel der Nachricht
prevMsgAttachment Wie oben, nur enthalten diese Readings die Daten der zuvor empfangenen Nachricht (n-1)
prevMsgGroupName
prevMsgSender
prevMsgText
prevMsgTimestamp
sentMsg Zuletzt gesendete Nachricht
sentMsgRecipient Empfänger der zuletzt gesendeten Nachricht. Enthält zumeist den Namen aus der Empfangsbestätigung und somit bei vielen Empfängern den zuletzt bestätigten Empfang.

Dies muss nicht zwingend auf die zuletzt gesendete Nachricht (sendMsg) passen, wenn mehrere Nachrichten versendet wurden.

sentMsgTimestamp Zeitstempel des Empfangs oder "pending" wenn noch keine Bestätigung vorliegt

Installation

Info green.pngDie Installation der Voraussetzungen ist derzeit (Januar 2021) identisch zur Beschreibung für das Modul SiSi, einem bereits etablierten (aber aktuell nicht weiterentwickelten) Modul zur Unterstützung des Signal Messenger Protokolls.

Installation in Kurzform:

  • Installation der Voraussetzungen, wie für SiSi beschrieben
  • Installation des signal-cli
  • Registrierung einer Rufnummer
  • Einrichtung der Kommunikation über D-Bus
  • Download und Installation des Moduls 50_Signalbot.pm

Einrichtung des Moduls

Siehe Forenthema Neues Modul: Signalbot.

Links