Signalbot: Unterschied zwischen den Versionen

Aus FHEMWiki
K (Formatierung)
(Kapitel zu Fernsteuerung und Authentifizieren eingefügt)
 
(36 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 6: Zeile 6:
|ModTechName=50_Signalbot.pm
|ModTechName=50_Signalbot.pm
|ModOwner=Adimarantis ({{Link2FU|39402|Forum}}/[[Benutzer Diskussion:Adimarantis‎|Wiki]])}}
|ModOwner=Adimarantis ({{Link2FU|39402|Forum}}/[[Benutzer Diskussion:Adimarantis‎|Wiki]])}}
Das Modul [[Signalbot]] ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst [https://signal.org Signal] aus FHEM heraus.
Das Modul [[Signalbot]] ermöglicht den Versand von Nachrichten über den Instant-Messaging-Dienst [https://signal.org Signal] aus FHEM heraus.


Zeile 16: Zeile 15:
Aktuell unterstützte Funktionen aus FHEM:
Aktuell unterstützte Funktionen aus FHEM:
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
* Versenden von einem oder mehreren Attachments (Bilder)
* Versenden von einem oder mehreren Attachments (Bilder) sowie Plots von SVG und DOIF
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Einlesen, Speichern und Übersetzen von Gruppennamen (statt base64 Strings)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Setzen, Empfangen und Übersetzen von Kontaktnamen (statt Telefonnummern)
* Einschränken von Gruppen oder Kontakten, auf die FHEM reagieren soll
* Einschränken von Gruppen oder Kontakten, auf die FHEM reagieren soll
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
* Direkte Verknüpfung mit dem [[Modul Babble|Babble]] Modul zur Interpretation von Befehlen
* Authentifizierte Befehle an FHEM senden ({{Link2CmdRef|Anker=GoogleAuth}})
* Authentifizierte Befehle an FHEM senden ({{Link2CmdRef|Anker=GoogleAuth}}) mit Favoriten
* Blockieren von Kontakten und Gruppen
* Blockieren von Kontakten und Gruppen
* Verwalten und Betreten/Verlassen von Gruppen
* Verwalten und Betreten/Verlassen von Gruppen
Neu mit 3.0:
 
* Registrierung von neuen Nummern inklusive Hilfestellung für Captchas
* Registrierung von neuen Nummern inklusive Hilfestellung für Captchas
* Linken von bestehenden Accounts zu FHEM
* Linken von bestehenden Accounts zu FHEM
Zeile 32: Zeile 31:
* Signalbot erzeugt keinen eigenen Prozess sondern integriert sich voll in die laufende FHEM Instanz (ist dadurch hoffentlich stabiler und verbraucht auch weniger Speicher)
* 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.
* 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
* 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.  
* 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).
* Die Möglichkeit von SVG oder DOIF Plots zu versenden (mit & wie bei anderen Anhängen, Details in den Beispielen)  
* Wurde mit und für die aktuelle Version 0.9.0 von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version vom Perl Modul Protocol::DBus (aktuell 0.19) benötigt
* Wurde mit und für die aktuelle Version von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version vom Perl Modul Protocol::DBus (aktuell 0.22) benötigt
* Wird aktiv (September 2021) gewartet (letztes Update für SiSi auf github ist von August 2018)
* Wird aktiv (Januar 2024) gewartet (letztes Update für SiSi auf github ist von August 2018)


=== "set" Funktionen im Detail ===
=== "set" Funktionen im Detail ===
Zeile 49: Zeile 48:
Ein paar Beispiele  
Ein paar Beispiele  
   send @+498514711 Hallo Signal
   send @+498514711 Hallo Signal
   send #FHEM &/tmp/foto.jpg Ein Bild schicken
   send #FHEM &/tmp/foto.jpg                             Ein Bild schicken
   send "@Mein Freund" Leerzeichen durch Anführungszeichen um den ganzen Teilbefehl
   send "@Mein Freund"                                   Leerzeichen durch Anführungszeichen um den ganzen Teilbefehl
   send @Joerg #FHEM #Familie Jeder Empfänger, jede Gruppe und Attachments können mehrfach vorkommen
   send @Joerg #FHEM #Familie                           Jeder Empfänger, jede Gruppe und Attachments können mehrfach vorkommen
   send "@({my $var=\"Joerg\";; return $var;;})" Perl Code mit Leerzeichen ausführen
   send "@({my $var=\"Joerg\";; return $var;;})"         Perl Code mit Leerzeichen ausführen
   send @(define dummy1 dummy) FHEM Befehl ausführen, wird aber nicht gesendet, da kein gültiger Empfänger zurück geliefert wird
   send @(define dummy1 dummy)                           FHEM Befehl ausführen, wird aber nicht gesendet, da kein gültiger Empfänger zurück geliefert wird
   send @Joerg &({plotAsPng(\'SVG_Aussentemperatur\')}) Einen FHEM SVG Plot verschicken oder
   send @Joerg &({plotAsPng(\'SVG_Aussentemperatur\')}) Einen FHEM SVG Plot verschicken oder
   send @Joerg "&({plotAsPng('SVG_Aussentemperatur')})" Einen FHEM SVG Plot verschicken
   send @Joerg "&({plotAsPng('SVG_Aussentemperatur')})" so - oder
  send @Joerg &SVG_Aussentemperatur                    so - oder
  send @Joerg "&SVG_Aussentemperatur,day,-1"            SVG Plot vom voherigen Tag
  send @Joerg &DI_uitable                              Sende erstes Widget aus einem DOIF mit definiertem uiTable
  send @Joerg "&DI_uitable,dev=outtemp,state"          Sende erstes Widget dass Werte aus der Device "outtemp" verwendet aus definiertem uiState
   send @Joerg Mehrzeilige Ausgabe:\nNeue Zeile
   send @Joerg Mehrzeilige Ausgabe:\nNeue Zeile
   send @Joerg Umlaute öäü und Emojis 🙃😆🤗🤑🤪 sowie 𝐅𝐨𝐫𝐦𝐚𝐭𝐢𝐞𝐫𝐮𝐧𝐠𝐞𝐧 direkt senden  
   send @Joerg Umlaute öäü und Emojis 🙃😆🤗🤑🤪 sowie 𝐅𝐨𝐫𝐦𝐚𝐭𝐢𝐞𝐫𝐮𝐧𝐠𝐞𝐧 direkt senden oder
  send @Joerg <nowiki><b>Fetter</b></nowiki> Text und Emojis :) :smile: - siehe get helpUnicode für Details
   send @Joerg Die Aussentemperatur ist [out_temp:temperature] Grad
   send @Joerg Die Aussentemperatur ist [out_temp:temperature] Grad
'''Tipp zu den Formatierungen''': Auf z.B. https://yaytext.com/ kann man sich seine UTF8 Kodierungen erstellen und nach FHEM per copy&paste einfügen. Vorrausetzung dürfte sein, dass die "locale" des Systems auf UTF8 eingestellt ist
'''Tipp zu den Formatierungen''': Auf z.B. https://yaytext.com/ kann man sich seine UTF8 Kodierungen erstellen und nach FHEM per copy&paste einfügen. Vorrausetzung dürfte sein, dass die "locale" des Systems auf UTF8 eingestellt ist
'''Hinweis:''' Signalbot bietet in den Device Details eine "send message" Zeile um bequem Nachrichten zu versenden. Hier gibt es jedoch durch das Webinterface einige Einschränkungen, z.B. in der Verwendung von Anführungszeichen. Für komplexere Nachrichten, daher möglichst "set send" verwenden.
===== Details zum Versenden von Plots =====
Seit Signalbot V3.5 wird eine vereinfachte Form der Versendung von SVG Plots und sogar von DOIF uiTable Widgets unterstützt (siehe [[DOIF/uiTable Schnelleinstieg]]). Entspricht der mit "&" übergebene Anhang einem FHEM Device, und ist dies vom Typ SVG oder DOIF, wird dies besonders behandelt.
Für SVG wird die Funktion "plotAsPng" dann intern aufgerufen. Es können dabei mit Komma getrennt noch der "Zoom" und das "Offset" angegeben werden, als ''"&SVG_Device,Zoom,Offset"''. Es wird empfohlen den Term in Anführungszeichen zu setzen, das z.B. DOIF die Kommas sonst als FHEM Befehlstrenner interpretiert. Zoom ändert nicht die Größe! Diese bitte ggf. im SVG Device anpassen.
Erlaubte Werte für Zoom: hour, qday, day, week, month, year, 10years, 20years
Offset dürfte üblicherweise eine negative Zahl sein, und gibt an wie oft man zurückblättert (Zoom gibt dabei die Einheit an).
Die Unterstützung der DOIF Widgets verwendet einige Internas von DOIF und daher kann die Kompatibilität mit zukünftigen DOIF Versionen leider nicht garantiert werden. Falls es nach einem DOIF update nicht mehr funktioniert, bitte in Forum posten. Widgets werden primär aus dem Attribut uiTable genommen, ist dies nicht vorhanden, oder wird der Parameter "state" angeben, schaut Signalbot auch in uiState nach. Eine spezielle Fehlerbehandlung gibt es derzeit nicht, sondern es kommt nur die Meldung, dass die Datei nicht gefunden wurde.
'''Syntax''': ''"&DI_device,param1=wert1,param2=wert2" -'' die Verwendung von Anführungszeichen ist bei der Verwendung innerhalb eines DOIF nötig, das die Kommas sonst als Befehlstrenner interpretiert werden.
Mögliche Parameter:
* id : Sequentielle Nummer des Widgets welches angezeigt werden soll. Dabei zählen auch seperate Beschriftungen. "id=" kann auch weggelassen werden und nur die Zahl angegeben werden. "id" hat Vorrang vor "dev" oder "val"
* dev : Identifiziert das Widget über das FHEM Device aus welchem das Widget seine Daten holt. Ist dies nicht eindeutig, wird das Erste in der Liste verwendet - kann mit "val" kombiniert werden
* val : dentifiziert das Widget über das FHEM Reading aus welchem das Widget seine Daten holt. Ist dies nicht eindeutig, wird das Erste in der Liste verwendet - kann mit "dev" kombiniert werden
* zoom: Zoomfaktor bei der SVG->PNG Umwandlung. Dies ändert nicht die Größe des Bildes so dass ggf. Teile abgeschnitten werden.
* sizex / sizey: Ändert die Größe des Bildes, aber nicht des Widgets. Es sollten also üblicherweise zoom, sizex und sizey kombiniert werden bis das Ergebnis passt oder die Größe gleich im DOIF Widget angepasst werden.
* state : (ohne =) Hole die Widget Definition nicht aus uiTable sondern aus uiState
'''Achtung''': Es gibt einen bekannten Fehler, dass die SVG library die '''Halbring'''-Darstellung in der uiTable card nicht verdaut und diese daher nicht verwendet werden kann


==== setContact <Number> <Contactname> ====
==== setContact <Number> <Contactname> ====
Zeile 78: Zeile 106:
==== joinGroup <group link> ====
==== joinGroup <group link> ====
Einer bestehenden Gruppe beitreten. Dazu ist eine Einladung über einen "group link" nötig, der das Format <nowiki>https://signal.group/ https://signal.group/....</nowiki> hat. Der einfachste Weg hierzu ist es, wenn aus der Signal App die Funktion "group link" verwendet wird und der Link dann per Signal an den FHEM User gesendet wird. Sofern das ''autoJoin'' Attribut gesetzt ist, wird dieser erkannt und FHEM tritt der Gruppe automatisch bei.
Einer bestehenden Gruppe beitreten. Dazu ist eine Einladung über einen "group link" nötig, der das Format <nowiki>https://signal.group/ https://signal.group/....</nowiki> hat. Der einfachste Weg hierzu ist es, wenn aus der Signal App die Funktion "group link" verwendet wird und der Link dann per Signal an den FHEM User gesendet wird. Sofern das ''autoJoin'' Attribut gesetzt ist, wird dieser erkannt und FHEM tritt der Gruppe automatisch bei.
==== reply <message> ====
Wie "send", nur kann der Empfänger weggelassen werden - stattdessen wird die Nachricht an den Absender der zuletzt empfangenen Nachricht gesendet
==== trust <Contact|"all"> ====
Setzt den entsprechenden Kontakt - oder mit "all" alle bekannten Kontakte auf "TRUSTED_UNVERIFIED". Dies ist manchmal nötig um von diesem Kontakt problemlos Nachrichten zu empfangen. Der Kontakt ist damit nicht vollständig verifiziert - dazu gibt es "trustVerified". Details über den Status eines Kontakts gibt es per "get identityDetails"
Die Liste ist mit Kontakten vorbefüllt, die noch "UNTRUSTED" sind - steht dort nur "all" sind also alle bekannten Kontakte mindestens "TRUSTED_UNVERIFIED". Sofern die Liste der Kontakte länger als 20 ist, ist die Nummer allerdings in ein Textfeld einzugeben, da das Dropdown sonst zu lang werden würde.
==== trustVerified <Contact> <SafetyNumber> ====
Validiert einen Kontakt als "TRUSTED_VERIFIED". Die SafetyNumber sollte üblicherweise auf einem sicheren Weg vom jeweiligen Kontakt übermittelt werden (z.B. vom persönlich vom Display abtippen oder über einen verifizierten Kommunikationskanal senden). Die Nummer ist aber symmetrisch (also für jedes Sender und Empfänger Paar gleich) und wird mit "get identityDetails" angezeigt und kann dort verglichen und dann einfach mit copy&paste übernommen werden. Kontakte denen voll vertraut wird, können via Signal Kommandos an FHEM senden, sofern ''authTrusted=yes'' gesetzt ist.


==== quitGroup <Groupname> ====
==== quitGroup <Groupname> ====
Zeile 87: Zeile 126:
==== unblock #<Groupname>|<Contact> ====
==== unblock #<Groupname>|<Contact> ====
Hebt die Blockierung wieder auf.
Hebt die Blockierung wieder auf.
==== updateProfile <name> [&<Avatar picture>] ====
Setzt den Namen des Anwenders und optional ein Avatar Bild.


=== "set" Sonderfunktionen zur Registrierung ===
=== "set" Sonderfunktionen zur Registrierung ===
Zeile 117: Zeile 159:
Dies ist der letzte Schritt der Registrierung. Danach ist Signalbot einsatzbereit.
Dies ist der letzte Schritt der Registrierung. Danach ist Signalbot einsatzbereit.


==== link ====
==== link <Name> ====
Zeigt einen QR Code an, den man mit der Signal App auf dem Smartphone scannen kann um FHEM als "Mitbenutzer" zu registrieren. FHEM erhält dann alle Nachrichten und gesendete Nachrichten haben den Absender des Telefons. Dies ist ein einfacher und schneller Weg um Signalbot auszuprobieren, sollte aber nicht für die produktive Benutzung verwendet werden, um unerwünschte Nebeneffekte zu vermeiden.
Zeigt einen QR Code an, den man mit der Signal App auf dem Smartphone scannen kann um FHEM als "Mitbenutzer" zu registrieren. FHEM erhält dann alle Nachrichten und gesendete Nachrichten haben den Absender des Telefons. Dies ist ein einfacher und schneller Weg um Signalbot auszuprobieren, sollte aber nicht für die produktive Benutzung verwendet werden, um unerwünschte Nebeneffekte zu vermeiden. Da FHEM nicht benachrichtigt wird, wenn der "link" zustande gekomme ist, muss danach manuell ein "set reinit" durchgeführt werden.
 
Der optionale Name (wenn leer wird "FHEM" verwendet) dient zur Identifizierung.
 
Die angezeigte URI kann mittels "addDevice" auch dafür verwendet werden zwei FHEM Instanzen miteinander zu verküpfen, welches auf der Hauptinstanz ausgeführt wird.
 
==== addDevice <device URI> ====
Fügt eine andere Instanz als "Mitbenutzer" hinzu. Die URI wird mit "set link" auf der anderen (nicht registrierten) FHEM Instanz erzeugt.
 
Dabei ist zu beachten, dass alle Nachrichten/Befehle an beide Instanzen gehen, was bei entsprechenden Triggern zu beachten ist. Ansätze dazu sind mit "allowedPeer" auf unterschiedliche Sender zu reagieren, unterschiedliche cmdKeyWord's zu setzen etc.
 
==== removeDevice <deviceID> ====
Entfernt einen Mitbenutzer anhand seiner deviceID. Diese kann mit "get devices" abgefragt werden. Wenn nur Mitbenutzer verlinkt ist, ist da üblicherweise "2" da "1" dem Hauptbenutzer zugeordnet wird.


=== "get" Funktionen im Detail ===
=== "get" Funktionen im Detail ===
Zeile 125: Zeile 179:
Öffnet ein Fenster mit allen bekannten Kontakten mit Telefonnummer und Kontaktname sowie deren "blocked" Status. Mit dem Parameter "nonblocked" werden geblockte Kontakte ausgeblendet. Als Name wird primär der selbstdefinierte Kontaktname angezeigt. Sofern keiner definiert ist, wird der durch den Kontakt selbst definierte Profilname angezeigt.  
Öffnet ein Fenster mit allen bekannten Kontakten mit Telefonnummer und Kontaktname sowie deren "blocked" Status. Mit dem Parameter "nonblocked" werden geblockte Kontakte ausgeblendet. Als Name wird primär der selbstdefinierte Kontaktname angezeigt. Sofern keiner definiert ist, wird der durch den Kontakt selbst definierte Profilname angezeigt.  


''Achtung: Profilnamen werden nur all 24h aktualisiert. Ein Änderung wird also ggf. nicht sofort sichtbar. Ist kein Kontaktname und auch kein Profilname definiert, bleibt das Feld leer. Mit signal-cli 0.8.1 führt das aktuell noch zu einer Fehlermeldung im Logfile, die ignoriert werden kann. Das dürfte mit der nächsten Version behoben sein.''
==== chat <Contact|Group> ====
Signalbot speichert eine kurze Chat Historie per Kontakt oder Gruppe die hiermit abgerufen wird. Die Gruppen sind aktuell mit "+" statt "#" gekennzeichnet, da es mit dem "#" Zeichen Probleme in der Implementierung gab.
 
Die Historie wird nicht abgespeichert, ist also nach einem Neustart wieder weg und beschränkt sich auf 20 Zeilen.  


==== groups all|active|nonblocked ====
==== groups all|active|nonblocked ====
Zeile 132: Zeile 189:
==== accounts ====
==== accounts ====
Zeigt alle aktuell in signal-cli registierten Telefonnummern an, die mit "set signalAccount" verwendet werden können.
Zeigt alle aktuell in signal-cli registierten Telefonnummern an, die mit "set signalAccount" verwendet werden können.
==== devices ====
Zeigt alle verlinkten Mitbenutzer an. Üblicherweise hat dies nur einen Eintrag (den Hauptbenutzer = aktuelle Instanz). Die ID Nummer können mit "removeDevice" verwendet werden um Mitbenutzer zu entfernen.
==== favorites ====
Listet die definierten Favoriten im Attribut "favorites" (siehe unten) in tabellarischer Form auf. Nützlich um zu prüfen ob das Attribut korrekt befüllt ist.
==== helpUnicode ====
Zeigt alle unterstützten Tags zur Formattierung von Nachrichten mittels HTML oder Markdown Tags.
'''Achtung''': Die Funktion muss über dass Attribut ''formatting'' aktiviert werden.
==== identityDetails <Contact> ====
Zeigt Systemdetails zu einem Kontakt an. Neben dem vollen Namen, dem Trust Level (UNTRUSTED,TRUSTED_UNVERIFIED oder TRUSTED_VERIFIED), die SafetyNumer die mit "set trustVerified" verwendet werden kann um den TRUSTED_VERIFIED Status zu setzen, wann der Kontakt zu signal-cli hinzugefügt wurde sowie einen QR-Code der mit der Signal App gescannt werden kann um umgekehrt TRUSTED_VERIFIED für FHEM auf dem Telefon zu setzen.


=== Attribute im Detail ===
=== Attribute im Detail ===
Zeile 139: Zeile 210:
==== authDev ====
==== authDev ====
Name des genutzten GoogleAuth device. Dies wird üblicherweise automatisch gesetzt, sofern bereits ein GoogleAuth device im System definiert ist, sobald das ''authTimeout'' gesetzt wird.
Name des genutzten GoogleAuth device. Dies wird üblicherweise automatisch gesetzt, sofern bereits ein GoogleAuth device im System definiert ist, sobald das ''authTimeout'' gesetzt wird.
==== authTrusted ====
Falls auf "yes" gesetzt, dürfen Kontakte die den Vertrauensstatus "TRUSTED_VERIFIED" haben auch ohne GoogleAuth Kommandos an FHEM senden. Da Signal z.B. mit diesem Mechanismus vor Accountübernahme, Handywechsel etc. schützt, ist die Identität des Kontakts zweifelsfrei sichergestellt und die umständliche Eingabe eines Codes von GoogleAuth kann entfallen.


==== autoJoin 0|1 ====
==== autoJoin 0|1 ====
Falls auf 1 gesetzt, reagiert FHEM automatisch auf Einladungslinks (siehe ''joinGroup'') und tritt der Gruppe bei
Falls auf 1 gesetzt, reagiert FHEM automatisch auf Einladungslinks (siehe ''joinGroup'') und tritt der Gruppe bei


==== commandKeyword ====
==== cmdKeyword ====
Eine Zeichenkette aus einem oder mehreren Zeichen, die am Anfang einer Nachricht stehen kann, damit FHEM die restliche Nachricht ungefiltert als Kommando ausführt. Die Funktion ist über GoogleAuth geschützt, d.h. ein Benutzer muss sich erst mit einem gültigen GoogleAuth Token legitimieren und bleibt entsprechend des ''authTimeout'' Attributs für gewisse Zeit authorisiert.
Eine Zeichenkette aus einem oder mehreren Zeichen, die am Anfang einer Nachricht stehen kann, damit FHEM die restliche Nachricht ungefiltert als Kommando ausführt. Die Funktion ist über GoogleAuth geschützt, d.h. ein Benutzer muss sich erst mit einem gültigen GoogleAuth Token legitimieren und bleibt entsprechend des ''authTimeout'' Attributs für gewisse Zeit authorisiert.


''Beispiel:''  
''Beispiel:''  


Man setzt ''commandKeyword'' auf "=" , dann kann man ''"=123456 set lamp off"'' senden. Im weiteren Verlauf reicht ''"=set lamp on"'' solange bis der Timeout abgelaufen ist.
Man setzt ''cmdKeyword'' auf "=" , dann kann man ''"=123456 set lamp off"'' senden. Im weiteren Verlauf reicht ''"=set lamp on"'' solange bis der Timeout abgelaufen ist.


Zur Authorisierung muss nicht zwingend gleich ein Befehl mitgesendet werden. Sofern ''allowedPeer'' gesetzt ist, muss der Absender zusätzlich in dieser Liste stehen.
Zur Authorisierung muss nicht zwingend gleich ein Befehl mitgesendet werden. Sofern ''allowedPeer'' gesetzt ist, muss der Absender zusätzlich in dieser Liste stehen.
Zeile 177: Zeile 251:
==== registerMethod <SMS|Voice> ====
==== registerMethod <SMS|Voice> ====
Stellt die Registrierungsmethode (Rückmeldung des Verifizierungscodes) auf SMS oder Sprachanruf um.
Stellt die Registrierungsmethode (Rückmeldung des Verifizierungscodes) auf SMS oder Sprachanruf um.
==== cmdFavorites ====
Definiert eine Zeichensequenz die bei remote Befehlen (siehe ''cmdKeyword'') als Favorit interpretiert wird. Details siehe unter ''favorites''. Da Favoriten vor FHEM Befehlen ausgewertet werden, sollte z.B. "set" nicht verwendet werden.
==== formatting <none|html|markdown|both> ====
Aktiviert die Ersetzung von html-ähnlichen Formatierungen (z.B. <nowiki><b>bold text</b></nowiki>) und/oder Markdown (z.B. __italic text__) um diese direkt in ASCII angeben zu können, anstatt nur per copy&paste.
Die komplette Liste von Tags/Ersetzungen kann über die ''get helpUnicode'' Funktion direkt im Model angezeigt werden.
==== favorites <[alias1]><-><command1>;<[alias2]><-><command2>;.... ====
Definiert Favoriten um remote Befehle (siehe ''cmdKeyword'') abzukürzen.
Einträge werden durch Semikolon getrennt und automatisch durchnummeriert.
Optional kann in eckigen Klammern "[]" ein alias angebenben werden, sowie ebenfalls optional dem Befehle ein Minuszeichen "-" vorangestellt werden, womit für diesen Befehl keine vorherige GoogleAuth Authentifizierung zu erfolgen hat.
'''Wichtig:''' Favoriten funktionieren nur wenn ''cmdKeyword, cmdFavorites, authTimeout, authDev'' und ''favorites'' gesetzt sind.
'''Beispiele''' (angenommen cmdKeyword="/" , cmdFavorites="fav", favorites="set lamp on;[off]set lamp off;[hi]-set talk say Jemand zuhause"):
{| class="wikitable"
|+
!Befehl
!Effekt
|-
|/fav 1
|Fehler weil nicht authentifiziert
|-
|/fav 3
|"set talk" Befehl wird ausgeführt, da "-" Befehle ohne Authentifizierung funktionieren
|-
|/fav hi
|"set talk" Befehl wird ausgeführt
|-
|/123456
|GoogleAuth Token setzen um remote Befehle freizuschalten
|-
|/fav 1
|"set lamp on" wird ausgeführt
|-
|/fav off
|"set lamp off" wird ausgeführt
|-
|/fav
|Liste all Favoriten mit IDs wird ausgegeben
|}


=== Readings im Detail ===
=== Readings im Detail ===
Zeile 239: Zeile 358:
* CPAN Seite des Perl Moduls zur [https://metacpan.org/pod/Protocol::DBus DBus Kommunikation]
* CPAN Seite des Perl Moduls zur [https://metacpan.org/pod/Protocol::DBus DBus Kommunikation]
Vorbereitung:
Vorbereitung:
Modul per "define <name> Signalbot" definieren.


Das Script "signal_install.sh" aus der Detailseite des Moduls oder vom [https://svn.fhem.de/fhem/trunk/fhem/contrib/signal/ FHEM SVN] runterladen und ins Verzeichnis eines beliebigen "sudo"-fähigen Users kopieren.
Das Script "signal_install.sh" aus der Detailseite des Moduls oder vom [https://svn.fhem.de/fhem/trunk/fhem/contrib/signal/ FHEM SVN] runterladen und ins Verzeichnis eines beliebigen "sudo"-fähigen Users kopieren.
Zeile 265: Zeile 382:
|start
|start
|Starten des singal service über systemd bzw. im Container des Dbus daemon and signal-cli Daemon
|Starten des singal service über systemd bzw. im Container des Dbus daemon and signal-cli Daemon
|-
|backup
|Erstellt ein Archiv aller relevanten Scripts und Einstellungen (z.B. für einen System Umzug) in der Datei signal-backup.tar.gz
|-
|restore
|Schreibt die Archive Datei signal-backup.tar.gz ins System zurück
|}
|}
Im Normalfall kann das script einfach unter root Rechten, also mit
Im Normalfall kann das script einfach unter root Rechten, also mit
  sudo ./signal_install.sh
  sudo -E ./signal_install.sh
aufgerufen werden (wenn das Script per Download geholt wurde, muss es vorher noch mit "chmod a+x signal_install.sh" ausführbar gemacht werden). Wenn kein Argument übergeben wird, dann wird automatisch der Ablauf ''system -> install -> test'' durchlaufen.
aufgerufen werden (wenn das Script per Download geholt wurde, muss es vorher noch mit "chmod a+x signal_install.sh" ausführbar gemacht werden). Wenn kein Argument übergeben wird, dann wird automatisch der Ablauf ''system -> install -> test'' durchlaufen.


Zeile 273: Zeile 396:


'''Hinweis:''' Es prüft außerdem ab, ob es im Container läuft. Dieser Modus ist nur dafür gedacht, wenn mein FHEM/Signal Container Script verwendet wurde. In anderen Container Umgebungen wird es üblicherweise nicht funktionieren. Details dazu weiter unten.
'''Hinweis:''' Es prüft außerdem ab, ob es im Container läuft. Dieser Modus ist nur dafür gedacht, wenn mein FHEM/Signal Container Script verwendet wurde. In anderen Container Umgebungen wird es üblicherweise nicht funktionieren. Details dazu weiter unten.
Dann Modul per '''"define <name> Signalbot"''' definieren.


=== Registrierung ===
=== Registrierung ===
Zeile 287: Zeile 412:
FHEM führt hierbei durch den Prozess mit Hilfestellungen
FHEM führt hierbei durch den Prozess mit Hilfestellungen


Ablauf:[[Datei:Signalbot Captcha Chrome.png|mini|Captcha in Chrome]]
Ablauf:
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Link ist auch direkt in FHEM verfügbar
# [https://signalcaptchas.org/registration/generate.html Captcha Seite] von Signal aufrufen. Link ist auch direkt in FHEM verfügbar
# Im Developermode (F12) und nach erfolgreichem Lösen des Captchas (wenn der Bildschirm leer bleibt, ist es auch erfolgreich gelöst) macht der Browser ein redirect auf signalcaptcha://. Das versteht der Browser aber nicht und macht gar nichts.
# Nach erfolgreichem Lösen des Captchas erscheint ein Link "Signal öffnen" bzw. unter Windows besteht eine Automatisierungsoption (siehe unten)
# Der String steht aber bei Firefox in der Console (recht einfach zu finden), beim Chrome muss man auf Network gehen, mit Ctrl+R refreshen und dann in der Spalte "Name" nach einem kryptischen String suchen. Dass dieser mit signalcaptcha anfängt, sieht man erst im Tooltipp, da der Anfang abgeschnitten wird.
# Üblicherweiser (Browserspezifisch) kann hier mit Rechtsklick und "Adresse des Links kopieren" das "signalcaptcha" kopiert werden
# Diesen String dann in FHEM bei "set captcha" eintragen. Jetzt sollte die Registrierung erfolgreich weitergehen (SMS/Anruf).
# Diesen String dann im "set captcha" Befehl eintragen und dann sollte die Registrierung weitergehen (SMS/Anruf)
Anbei Screenshots von Firefox und Chrome zum besseren Verständnis.
#* SMS: Hier sollte relativ zeitnah eine SMS mit einem 6-stelligen Code übermittelt werden
[[Datei:Signalbot Captch Firefox.png|mini|Captcha im Firefox]]
#* Voice: Die Registrierung per Sprachanruf ist mit einigen Hürden versehen. Man muss erst mit SMS registrieren, 1 Minute warten, dann mit Voice. Ab Signalbot V3.19 wird dieser Vorgang automatisiert. Dauert aber durch die zwingende Wartezeit von 1 Minute ein wenig.


'''Captcha "Automatisierung":'''  
'''Captcha "Automatisierung":'''  
Zeile 323: Zeile 448:


== Umstieg von SiSi ==
== Umstieg von SiSi ==
Alle die bereits SiSi verwenden können Signalbot erstmal gefahrlos parallel installieren. Einfach Modul ins FHEM Verzeichnis, reload / restart und "define".
Da SiSi eine inzwischen sehr alte '''signal-cli''' Version verwendet, die sehr wahrscheinlich nicht mehr voll abwärtskompatibel ist, wird von einer einfachen Migration abgeraten.


Signalbot benötigt allerdings eine andere Dbus Implementierung (Protocol::DBus), diese muss erst installiert werden:
Die Installation und Neuregistrierung der Nummer ist inzwischen soweit vereinfacht worden, dass diese Vorgehensweise weniger aufwändig ist.
:<syntaxhighlight lang="bash">cpan install -f Protocol::DBus</syntaxhighlight>
Probleme durch eine veraltete '''signal-cli''' Version sind aber nicht ausgeschlossen. Daher keine Support Anfrage ohne vollständigen Umstieg.


Wer komplett umsteigen möchte, kann dies dann mit dem Installer Script tun. Gegebenenfalls Pfade im Script anpassen. Eine bestehende Registrierung wird dann übernommen und muss nicht erneut erfolgen (keine Garantie, dass dies für sehr alte '''signal-cli''' Versionen funktioniert). Wer's ganz sauber haben will, löscht aber alte Installationsreste.
Ohne Garantie, dass dies mit der aktuellen signal-cli/Signalbot Version noch funktioniert hier trotzdem die potentielle Migration:


Signalbot allerdings eine andere Dbus Implementierung (Protocol::DBus), diese muss erst installiert werden:
:<syntaxhighlight lang="bash">cpan install -f Protocol::DBus</syntaxhighlight>
Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:
  SIGNALPATH=/opt/fhem
  SIGNALPATH=/opt/fhem
Zeile 343: Zeile 468:


=== Umzug auf ein neues System ===
=== Umzug auf ein neues System ===
Dazu einfach das Script mit dem Argument "remove" starten. Die alte Konfiguration wird dabei im Home Verzeichnis des aktuellen Benutzers als ''~/signalconf.tar.gz'' gesichert.
Dazu einfach das Script mit dem Argument "backup" starten. Die alte Konfiguration wird dabei im Home Verzeichnis des aktuellen Benutzers als ''~/signal-backup.tar.gz'' gesichert.


auf dem neuen System dann
auf dem neuen System dann diese Datei wieder ins Home und entsprechend das Script mit "restore" laufen lassen.
cd /
== Eigene native Library übersetzen ==
sudo tar xvf ''signalconf.tar.gz''
Signal-cli ist zwar überwiegend in Java geschrieben, hat aber leider eine binäre Library die zwingend benötigt wird. Ohne diese startet der Service nicht.
Dann wie üblich das Install Script ausführen.


== Eigene native Libraries übersetzen ==
Der Installler lädt automatisch die korrekte Library für unterstützte Architekturen und ersetzt die am64/glibc-2.31 die von signal-cli standardmäßig mitgeliefert wird. Unterstützt werden aktuell:
Signal-cli ist zwar überwiegend in Java geschrieben, hat aber leider zwei binäre libraries die zwingend benötigt werden. Ohne diese Libraries startet der Service nicht.
* Raspberry (armv7l) für Buster (glibc2.28) und Bullseye (glibc2.31)
 
* Raspberry 64-bit (aarch64) für glibc2.28 (ungetestet, sollte für Buster und Bullseye funktionieren)
Das Install Script kann aktuell automatisch die Standard Libraries (Stand signal-cli 0.9.0 ist das für am64 mit glibc-2.31 - was z.B. Ubuntu 20.04 verwendet) durch native libraries für Raspberry (armv7l) unter "Buster" ersetzen.
* AMD/Intel 64-bit (amd64) für glibc2.28 und glibc2.31 (Ubuntu 18,20,22, Debian 10,11 u.a.)
 
Es gibt mehrere github Projekte um signal-cli die auch fertig übersetzte libsignal_jni.so im Angebot haben (einfach mal suchen). Man kann sich die Library aber auch selbst übersetzen.
Meine apt-packages unterstützen zusätzlich noch amd64/libc-2.27, was z.B. Ubuntu 18.04 verwendet. Was aber jetzt wenn ich eine andere Architektur oder glibc habe?
 
Es gibt mehrere github Projekte um signal-cli die auch fertig übersetzte libsignal_jni.so und libzkgroup.so haben (einfach mal suchen), es ist aber gar nicht so schwer die selber zu übersetzen.


Ich gehe dabei davon aus, dass eine (wenn auch inkompatible) Installation von signal-cli bereits erfolgt ist und z.B. alle Java libraries an Ort und Stelle sind.
Ich gehe dabei davon aus, dass eine (wenn auch inkompatible) Installation von signal-cli bereits erfolgt ist und z.B. alle Java libraries an Ort und Stelle sind.


Erstmal brauchst du "rust":
Es werden eine Reihe von Programmen benötigt. Diese Liste ist möglicherweise nicht vollständig, je nachdem wie eurer System konfiguriert ist:<syntaxhighlight lang="shell">
 
sudo apt-install git build-essential clang cmake openjdk-17-jdk-headless
<code>sudo curl <nowiki>https://sh.rustup.rs</nowiki> -sSf | sh</code>
sudo curl https://sh.rustup.rs -sSf | sh
 
</syntaxhighlight>Es ist hier wichtig, dass die libsignal-client in der Version passt, daher in der signal-cli Installation checken<syntaxhighlight lang="shell">
Dann die zkgroup libs übersetzen:
ls /opt/signal/lib/libsignal-client*
 
</syntaxhighlight>Und die Versionsnummer notieren (für signal-cli 0.11.3 ist das 0.20.0)
<code>git clone git@github.com:signalapp/zkgroup.git</code>
 
<code>cd ffi/java</code>
 
<code>make</code>
 
Da kommt am Schluss ein Fehler, den kann man aber ignorieren, wenn die library erfolgreich erzeugt wurde.
 
''libzkgroup.so'' aus ''target/release/'' nach ''/opt/signal/lib'' kopieren
 
Jetzt libsignal-client übersetzen:
 
<code>git clone git@github.com:signalapp/libsignal-client.git</code>
 
<code>cd java</code>
 
<code>./build_jni.sh desktop</code>
 
''libsignal_jni.so'' aus ''target/release/'' nach ''/opt/signal/lib'' kopieren
 
Libraries in den Java .jar Files durch die selbst compilierten ersetzen:
 
<code>cd /opt/signal/lib</code>


<code>sudo -u signal-cli zip -u signal-client-java-*.jar libsignal_jni.so</code>
Jetzt entsprechend auschecken<syntaxhighlight lang="shell">
git clone git@github.com:signalapp/libsignal-client.git
cd libsignal-client
git checkout v0.20.0
cd java
./build_jni.sh desktop


<code>sudo -u signal-cli zip -u zkgroup-java-*.jar libzkgroup.so</code>
</syntaxhighlight>''libsignal_jni.so'' aus ''target/release/'' nach ''/opt/signal/lib'' kopieren


Dann Service neu starten
Libraries in den Java .jar Files durch die selbst compilierten ersetzen:<syntaxhighlight lang="shell">
cd /opt/signal/lib
sudo -u signal-cli zip -u signal-client-java-*.jar libsignal_jni.so
</syntaxhighlight>Dann Service neu starten


<code>sudo service signal start</code>
<code>sudo service signal start</code>
Zeile 419: Zeile 525:
'''Achtung:''' Das Ganze ist experimentell und für eine einmalige Installation/Start gebaut. Wenn fhem, signal-cli oder der dbus-daemon im Docker beendet werden, dann muss man diese evtl. selbst wieder nachstarten. Das kann man sicher noch einiges verbessern. Sinnvollerweise nimmt man die erzeugten Config Dateien und Scripte eher als Anregung für eine eigene Konfiguration. Verbesserungsvorschläge gerne auch im Forum.
'''Achtung:''' Das Ganze ist experimentell und für eine einmalige Installation/Start gebaut. Wenn fhem, signal-cli oder der dbus-daemon im Docker beendet werden, dann muss man diese evtl. selbst wieder nachstarten. Das kann man sicher noch einiges verbessern. Sinnvollerweise nimmt man die erzeugten Config Dateien und Scripte eher als Anregung für eine eigene Konfiguration. Verbesserungsvorschläge gerne auch im Forum.


== Favoriten und erweiterte Command Funktionen mit einem notify ergänzen ==
== Versenden von Nachrichten ohne FHEM ==
Signalbot kann über [[DOIF]]s/[[notify]]s problemlos um individuelle Funktionen erweitert werden. Der hier beschriebene Ansatz ergänzt eine Favoritenverwaltung und erlaubt die direkt Ausführung von FHEM Befehlen entweder mit oder ohne Authentifizierung via GoogleAuth.
Falls jemand auch aus Shell Scripten heraus Signal Nachrichten versenden möchte, kann die FHEM signal-cli Installation am einfachsten über den "dbus-send" Befehl mitverwendet werden:


Die Beschreibung hier erfolgt auf Basis von Signalbot Version "Signalbot:2.0.1-beta signal-cli:0.8.1 Protocol::DBus:0.16". Bei künftigen Versionen können sich ggf. Änderungen ergeben.
<code>dbus-send --system --type=method_call --print-reply --dest=org.asamk.Signal /org/asamk/Signal/_xxxxxx org.asamk.Signal.sendMessage string:Hallo array:string: string:+49yyyy</code>


'''Use Case / Szenario'''
''/org/asamk/Signal/_xxxxxx'' entspricht hier der registrierten Nummer und steht in FHEM Signalbot im Status ("connected to ..."). Dabei wird das "+" in der Nummer durch "_" ersetzt.


Das Signalbot Modul bietet über die Defintion von "allowedPeers" und durch die von Signal bereitgestellte Ende-zu-Ende Verschlüsselung bereits ein hohes Maß an Sicherheit. Für einfache Abfragen von Temperaturen etc. ist das aus Sicht des Autors absolut ausreichend. Diese Abfragen sollten über Favoriten mit möglichst wenig Tipp-Aufwand gesendet werden können.
Wichtig ist bei Dbus Nachrichten nicht nur der Name der Methode (sendMessage) sondern auch Typ und Reihenfolge der Parameter. Für ''sendMessage'' heisst das:
# Die eigentliche Nachricht als String
# Ein Array von Strings die Attachments enthalten (da man dies von der Kommandozeile eher nicht machen wird, erzeugt ''array:string'' hier einen leeren Parameter)
# Die Telefonnummer der Empfängers als String
Grundsätzlich kann man so alle Dbus Methoden von signal-cli ansteuern, welche unter https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc dokumentiert sind.


Für sicherheitskritische / sensible Aktionen ist aber eine zusätzliche Absicherung wünschenswert. Für solche Befehle bietet das Signalbot Modul die Integration von GoogleAuth bereits an. Auch diese Befehle können über Favoritendefinitionen abgekürzt werden. Das GoogleAuth Token wird dann vorab separt geschickt.
Einige Dinge sind aber nicht so komfortabel, z.B. kann man Gruppen nicht per Namen, sondern nur über einen langen base64-kodierten String ansteuern - hier übernimmst SignalBot eine benutzerfreundliche Übersetzung.


'''Voraussetzungen'''
Eine weitere Alternative ist dann einfach einen FHEM Befehl abzusetzen - z.B. per ''telnet'' Kommando.
* Das Signalbot Device wird mit "signalBot" benannt (alternativ muss eben der Code im Notify angepasst werden)
* Es werden zusätzliche Attribute via <code>userattr</code> zum Signalbot Device hinzugefügt: cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList <code>attr signalBot userattr cmdKeywordNoAuth cmdPatternNoAuth favPrefix favList</code>
'''Der Notify Code'''
<syntaxhighlight lang="perl">
signalBot:msgText.* {
my $msgText = ReadingsVal("signalBot", "msgText", "");
my $msgAuth = int(ReadingsVal("signalBot", "msgAuth", 0));
my $FhemCmd;
my $cmdPatternNoAuth = AttrVal("signalBot", "cmdPatternNoAuth", undef);
my $favPrefix = AttrVal("signalBot", "favPrefix", undef);
my $cmdKeyword = AttrVal("signalBot", "cmdKeyword", undef);
my $cmdKeywordNoAuth = AttrVal("signalBot", "cmdKeywordNoAuth", undef);
my @favarray;
my @patternarray;
my $favno;
my $favList;
my $retval;
my $msgSender = ReadingsVal("signalBot", "msgSender", "");
        my $msgGroup =  ReadingsVal("Signalbot", "msgGroupName", "");
if ($msgGroup ne "") { $msgSender = "#" . $msgGroup }
elsif (substr($msgSender, 0, 1) ne "+")  { $msgSender = "@" . $msgSender }


    # Sicherheitsprüfung für multi-Command Befehl
Alternativ geht es auch direkt über den signal-cli client. Dafür muss aber vorher der service beendet sein (Konflikt):
if (index($msgText, ";") >= 0{
  sudo service signal stop
  Log3("ntf_signalBot", 2, "ntf_signalBot: Semicolon detected, sender may try to send multiple commands in one line. Aborting!");
sudo -E -u signal-cli /opt/signal/bin/signal-cli -c /var/lib/signal-cli -u +49<registrierte Nummer> send -m "testmessage" +49<Empfänger>
  fhem("set signalBot send $msgSender Semicolon detected, command is ignored!");
  return;
}


# ggf. Favoriten auflösen
== Fernsteuerung und Authentifizierung ==
if ($favPrefix && substr($msgText, 0, length($favPrefix)) eq $favPrefix) {
Signalbot ermöglicht es FHEM über Signal fernzusteuern und dies auch abzusichern.
  $favno = $favPrefix eq $msgText ? 0 : int(substr($msgText, length($favPrefix)));
      @favarray = split(";", AttrVal("signalBot", "favList", undef));
 
  if ($favno == 0)  {
      # Favoritenliste zurückgeben
      Log3("ntf_signalBot", 4, "ntf_signalBot: list favorites");
  $favList = "";
  $favno = 1;
  foreach my $favLine (@favarray) {
$favLine =~ /^\[(.*)\]/;
    $favList .= $favPrefix . $favno . "\t" . $1 . "\n";
$favno++;
  }
  fhem("set signalBot send $msgSender $favList");
  return;
  } else {
      # favoriten verarbeiten
      $FhemCmd = $favarray[$favno-1];
      # wenn ein Alias definiert ist, dann den Befehlsteil aus dem Favoriten extrahieren
      if (index($FhemCmd, "=") >= 0) {
    $FhemCmd = substr($FhemCmd, index($FhemCmd, "=")+1);
      }
      Log3("ntf_signalBot",3,"ntf_signalBot: FhemCmd after favorite substitution: $FhemCmd");
  }


  # prüfe auf authorsiertes Command (nur wenn Favoriten expandiert wurden, um doppelte Ausführung zu vermeiden
Um die Fernsteuerung zu aktivieren muss zuerst über das Attribut "cmdKeyword" festgelegt werden, woran Signalbot erkennen soll, dass es sich um einen Befehl handelt. In dieser Dokumentation gehe ich jetzt davon aus das "/" als Keyword gesetzt ist. Das Keyword kann auch mehrere Zeichen lang sein.
  if ($cmdKeyword && substr($FhemCmd, 0, length($cmdKeyword)) eq $cmdKeyword)  {
  if ($msgAuth)  {
Log3("ntf_signalBot", 3, "ntf_signalBot: execute authenticated cmd");
$FhemCmd = substr($FhemCmd, length($cmdKeyword));
$retval = fhem($FhemCmd);
if ($retval) {
    fhem("set signalBot send $msgSender $retval");
}
  } else {
# Hinweis auf nicht authorsiertes Command
fhem("set signalBot send $msgSender You are not authorized to execute authenticated commands");
  }
  }
} else {
  $FhemCmd = $msgText
}


# prüfe auf nicht authorsiertes Command
Sendet man jetzt "/set lamp on" an Signalbot, so führt dieser das entsprechende set Kommando direkt aus.
if ($cmdKeywordNoAuth && substr($FhemCmd, 0, length($cmdKeywordNoAuth)) eq $cmdKeywordNoAuth)  {
  # prüfe patterns
      Log3("ntf_signalBot", 4, "ntf_signalBot: received non-authenticated cmd, checking patterns");
  @patternarray = split(";", AttrVal("signalBot", "cmdPatternNoAuth", undef));
  $FhemCmd = substr($FhemCmd, length($cmdKeywordNoAuth));


  my $res = 0;
Dies ist natürlich sicherheitstechnisch ein offenes Scheunentor und es gibt mehrere Methoden der Absicherung
  foreach my $secLine (@patternarray) {
 
$res += eval '$FhemCmd =~ /' . $secLine . '/';
==== Attribut allowedPeer ====
  }
Dieses Attribut enthält eine Komma-getrennte Liste von Nummer, Kontakt- oder Gruppennamen welche als gültige Absender akzeptiert werden. Ist es nicht gesetzt kann jeder mit Signalbot kommunizieren und Kommandos senden oder Events triggern
  if ($res > 0)  {
 
          Log3("ntf_signalBot", 3, "ntf_signalBot: execute non-authenticated cmd");
==== GoogleAuth ====
      $retval = fhem($FhemCmd);
Vorrausetzung ist, dass man in FHEM ein GoogleAuth Device angelegt hat und entsprechend auch die App auf dem Telefon. Näheres in der Commandref.
  if ($retval) {
 
    fhem("set signalBot send $msgSender $retval");
Über das Attribut "authDev" kann die GoogleAuth Device zugewiesen werden. Üblicherweise ist dies nicht erforderlich, da SignalBot dieses in System sucht und das Attribut automatisch setzt.
  }
 
  } else {
Um die Prüfung per GoogleAuth zu aktivieren wird das Attribut "authTimeout" (in Sekunden) gesetzt, welches definiert wie lange eine erfolgreiche Authentifierung gültig bleibt.
          Log3("ntf_signalBot", 2, "ntf_signalBot: non-authenticated cmd execution requested, but no pattern match");
 
      fhem("set signalBot send $msgSender You are not authorized to execute this command without authentication");
Wenn jetzt Befehle an FHEM gesendet werden, quittiert Signalbot diese mit "You are not authorized to execute commands". Zur Authentifizierung wird einfach die 6-stellige Nummer aus dem Google Authenticator mit vorangestelltem Keyword an FHEM gesendet, also z.B. "/123456"
  }
 
}
Man erhält die Meldung, dass man nur für gewisse Zeit (authTimeout) authentifiziert ist und kann Kommandos senden.
 
}
==== Trust ====
</syntaxhighlight>
Signal hat eine eigene Funktionalität um Kommunikationspartner zu überprüfen und Ihnen das Vertrauen auszusprechend. Siehe dazu "set trust" und "set trustVerified". Da die Authentifizierung per GoogleAuth auf Dauer lästig sein kann, besteht die Möglichkeit diese für verifizierte vertraute Nutzer zu umgehen. Dazu wird das Attribut "authTrusted" auf "yes" gesetzt. Nutzer denen nicht voll vertraut wird, müssen sich weiter authentifzieren.
Die Konfiguration erfolgt mit den Attributen am Signal Device. Diese kann z. B. wie folgt aussehen:
<pre>
attr signalBot cmdKeyword /
attr signalBot cmdKeywordNoAuth -
attr signalBot cmdPatternNoAuth get .*;;trigger .*;;getstate .*
attr signalBot favPrefix fav
attr signalBot favList [Wird später]=-trigger ntf_sayTTS "Es wird leider etwas später";;[Öffne Haustüre]=/set Flur_Tueroeffner press;;[Temperaturen]=-trigger listTemperatures
</pre>
Wichtig ist hier, dass <code>cmdKeyword</code> und <code>cmdKeywordNoAuth</code> unterschiedlich sind. '''Das "="-Zeichen darf nicht verwendet werden,''' weil es in der Favoritenliste für die Zuweisung verwendet wird. In der Favoritenliste müssen die FHEM Befehle mit einem Prefix versehen werden, entweder <code>cmdKeyword</code> oder <code>cmdKeywordNoAuth</code>. Ohne Authentifizierung dürfen <code>get, trigger</code> und <code>getstate</code> aufgerufen werden, alle anderen Befehle erfordern Authentifizierung.


'''Anwendung'''
====== Favoriten ======
Der Vollständigkeit halber sei hier noch erwähnt, dass man Befehlskürzel per Favoriten definieren kann. Details dazu in der Beschreibung der set Befehle und Attribute.


Im Chat hat man nun folgende Optionen:
Per Attribut "cmdFavorite" wird festgelegt welches Keyword die Favoritenauswahl triggert. Das könnte z.B. auch "/" sein, so dass "// 1" den ersten Favoriten triggert. Dass Attribute "favorites" enhält dann die eigentliche Definition der Favoritenliste.
* Liste aller Favoriten zurückgeben lassen: <code>fav</code>
* Einen Favoriten aufrufen: <code>fav<x></code>, also z. B. fav3 oder fav13
* Einen FHEM Befehl ohne Authentifizierung aufrufen: <code>-get hzgWZ ist_temp</code>
* Einen FHEM Befehl mit Authentifizierung aufrufen: <code>/set hzgWZ soll_temp 22</code>  davor muss via <code>/<token></code> also z.B. <code>/394848</code> das aktuelle GoogleAuth Token gesendet werden


== Troubleshooting / FAQ ==
== Troubleshooting / FAQ ==
Zeile 576: Zeile 605:


Führe '''sudo service signal start''' aus.
Führe '''sudo service signal start''' aus.
|-
|signal-cli läuft nach reboot oder restart nicht, aber ein manueller Start ist erfolgreich.
<code>sudo systemctl status dbus-org.asamk.Signal.service</code>
meldet einen timeout
|Möglicherweise dauert das Starten von signal-cli länger als der standard 90sec Timeout des systemd (langsames System, langsame SD-Karte bei Raspberry, viele gleichzeitiger Startprozesse bei Reboot).
Hier kann man in ''/etc/systemd/system/signal.service'' den Timeout erhöhen indem in der Sektion ''[Service]'' die Zeile
<code>TimeoutSec=200</code>
eingefügt wird.
|-
|-
|'''Bei Starten von signal-cli:'''
|'''Bei Starten von signal-cli:'''
Zeile 585: Zeile 626:


ERROR App - Missing required native library dependency: libsignal-client
ERROR App - Missing required native library dependency: libsignal-client
 
|Passiert üblicherweise auf dem '''Raspberry pi.''' Die Standard Distribution von signal-cli enthält eine x86 library libsignal_jni.so, die mit armv7l nicht kompatibel ist, welche im jar libsignal-client-*.jar enthalten sind. Das Install Script entfernt diese und ersetzt sie durch armv7l libraries die vom Signalbot Maintainer auf svn.fhem.de zur Verfügung gestellt werden.
oder
 
Support for new group V2 is disabled, because the required native library dependency is missing: libzkgroup
|Passiert üblicherweise auf dem '''Raspberry pi.''' Die Standard Distribution von signal-cli enthält eine x86 library libzkgroup.so und libsignal_jni.so, die mit armv7l nicht kompatibel ist, welche im jar ''zkgroup-java-*.jar'' bzw. signal-client-java-*.jar enthalten sind. Das Install Script entfernt diese und ersetzt sie durch armv7l libraries die vom Signalbot Maintainer auf svn.fhem.de zur Verfügung gestellt werden.
Irgendwo auf dem System vorhandene alte Versionen können aber versehentlich erwischt werden und diese Fehler produzieren. Als ersten Schritt mit
Irgendwo auf dem System vorhandene alte Versionen können aber versehentlich erwischt werden und diese Fehler produzieren. Als ersten Schritt mit


Zeile 597: Zeile 634:


Weitere Tests wenn der Fehler nicht behoben ist:
Weitere Tests wenn der Fehler nicht behoben ist:
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libzkgroup.so'' beziehungsweise ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Welche Library wird vom System verwendet: ''sudo ldconfig -v | grep libsignal_jni.so'' . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
# Check gibt es irgendwo noch eine andere lib.so  <code>sudo find / -name libzkgroup.so 2>/dev/null</code>  Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# Check gibt es noch irgendwo ein anderes jar  <code>sudo find / -name libsignal-client-*.jar 2>/dev/null</code>  Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# Check gibt es noch irgendwo ein anderes jar  <code>sudo find / -name zkgroup-java-*.jar 2>/dev/null</code>  Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
# (für den zweiten Fehler, die Schritte 2 und 3 mit libsignal_jni.so bzw. signal-client-java-*.jar durchführen
|-
|-
|Ich kann an Einzelempfänger senden und empfangen, aber nicht an Gruppen versenden
|Beim Start von signal-cli:
|Du hast wahrscheinlich den vorhergehenden Fehler (libzkgroup) irgendwo, aber er ist dir nicht aufgefallen. Vorgehensweise wie oben.
Fehler: Beim Laden der Klasse org.asamk.signal.Main ist ein LinkageError aufgetreten
 
java.lang.UnsupportedClassVersionError: org/asamk/signal/Main has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to xx.0
|Signal-cli benötigt seit der Version 0.13+ eine vorhandene Java 21 Installation. Ältere Systeme haben von Haus aus aber nur Java 11 oder 17.
Das Install Script kann hier helfen und eine Binärdistribution von OpenJDK 21 installieren und setzt JAVA_HOME im Startup des Service üblicherweise auch entsprechend.
 
Wenn signal-cli allerdings in der Kommandozeile ausgeführt wird, ist darauf zu achten das JAVA_HOME=/opt/java gesetzt ist (bzw. auch die von euch gewählte Java 21 Distribution).
 
Ein häufiger Fehler ist auch beim sudo das "-E" zu vergessen, denn nur so wird JAVA_HOME beim sudo "durchgereicht".
|-
|-
|Ich kann keiner Gruppe beitreten und/oder nichts an eine Gruppe schicken.
|Fehler beim Setzen des Captcha: "Incorrect captcha - e.g. needs to start with signalcaptcha://"
|
# Sicherstellen, dass das Captcha tatsächlich korrekt ist - am Besten die Automatisierung über die Windows Registry verwenden
# Alternativ kann die Registrierung auch in der Kommandozeile vorgenommen werden
<syntaxhighlight lang="bash">
sudo service signal stop
 
cd /opt/signal/bin/
 
sudo -E -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 register --voice --captcha signalcaptcha://03AG....
 
sudo -E -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 verify 12345
 
sudo service signal start
</syntaxhighlight>
|-
|Fehler: ''Untrusted Identity for "+49xxxxxxx"'' beim Versenden von Nachrichten.
 
Dieses Fehlerbild ist zu erwarten, wenn ein bereits bestehender Kontakt sich erneut bei Signal angemeldet hat (z.B. Handywechsel) und sich der Sicherheitscode dadurch geändert hat.
|Mit "set trust <Nummer>" das Vertrauen (unverified) zum Kontakt wieder herstellen.
Sollte das nicht reichen (Nachrichten kommen nicht an / werden nicht empfangen) siehe weiter unten "Ich kann Nachrichten ohne Fehler senden....."
|-
|Senden von Nachrichten schlägt fehl oder Nachrichten werden nicht versendet
|Zur Prüfung ob der Fehler in FHEM, der DBUS Konfiguration oder bei signal-cli liegt, sind im Kapitel "Versenden von Nachrichten ohne FHEM" Methoden beschrieben direkt mit Dbus oder von der Kommandozeile Nachrichten zu senden.
Sicherstellen, dass mit "updateProfile" ein Name für das aktuelle Profil angelegt ist, sonst werden Nachrichten möglicherweise nicht verschickt.
|-
|Signal-cli started nach "apt update/upgrade" unter Raspberry Bullseye oder Buster nicht mehr.
Fehlermeldungen z.B. wrong ELF class: ELFCLASS64 (Possible cause: can't load AARCH64 .so on a ARM platform)
 
oder
oder


Error in invite:org.asamk.Signal.Error.Failure: Cannot join a V2 group as self does not have a versioned profile
Fehler wenn signal-cli als service läuft im syslog:
|Die neuen V2 Gruppen benötigen zwingend einen Profil Namen. Sofern also nach der Registrierung keiner gesetzt wurde, kann man keine Gruppen verwenden.
Abhilfe:


'''sudo -E ./signal_install.sh name'''
Caused by: org.sqlite.NativeLibraryNotFoundException: No native library found for os.name=Linux, os.arch=aarch64, paths=[/org/sqlite/native/Linux/aarch64:/usr/java/packages/lib:/lib:/usr/lib]
|Seit März 2023 stellt Raspian anscheinend den Kernel auf 64bit um, sofern es sich um einen neueren 64-bit fähigen Raspberry handelt. Mit dem Befehl "arch" wird dann "aarch64" statt "armv7l" ausgegeben.
Aktuell hilft hier nur wieder auf den 32-bit Kernel umzustellen.


um einen Namen (und optional ein Avatarbild) festzulegen.
Dazu am Ende der /boot/config.txt die Zeile
:<code>arm_64bit=0</code>
einfügen. Das Mischmasch aus 64Bit Kernel und 32Bit libraries bringt den Java loader für native libraries durcheinander. Aktuell ist dazu keine andere Lösung bekannt.
|-
|-
|Fehler beim Setzen des Captcha: "Incorrect captcha - e.g. needs to start with signalcaptcha://"
|Die Registrierung schlägt fehl , z.B. mit der Fehlermeldung "Rate limit exceeded"
|
|
# Sicherstellen, dass das Captcha tatsächlich korrekt ist - am Besten die Automatisierung über die Windows Registry verwenden
# Ein paar Stunden warten und es dann nochmal probieren (bei Rate limit exceeded)
# Ein bekannter Fehler in signal-cli (0.9.0 / 0.9.2) führt du diesem Fehler, wenn bereits eine Registrierung in /var/lib/signal-cli/data für die zu registrierende Nummer existiert. Wenn das FIle und Directory der Nummer gelöscht werden, geht es manchmal
# Anderen Browser probieren - es gibt Berichte, dass Firefox nicht funktioniert - Chrome scheint hier die bessere Wahl zu sein
# Es existiert wahrscheinlich ein weiterer Bug in signal-cli der trotzdem die Registrierung aus FHEM/Dbus verhindert. Workaround ist diesen Schritt auf der Kommandozeile durchzuführen:  <code>sudo service signal stop</code>    <code>cd /opt/signal/bin/</code>    <code>sudo -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 register --voice --captcha signalcaptcha://03AG....</code>    <code>sudo -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 verify 12345</code>    <code>sudo service signal start</code>
|-
|Ich kann Nachrichten ohne Fehler senden, diese kommen aber beim Empfänger nicht an.
Ich empfange keine Nachrichten, obwohl diese vom Sender korrekt abgeschickt wurden.
|'''Möglicherweise liegt es daran, dass dem Kontakt nicht vertraut wird.'''
Am Handy in die Details des FHEM Kontakts gehen, Sicherheitsnummer anzeigen und als verifiziert markieren.
In FHEM "set trustVerified" mit der Telefonnummer des Kontakts und dessen Sicherheitsnummer ausführen.
Damit man die Sicherheitsnummer nicht abtippen muss, kann man diese auch mit "get identityDetails" anzeigen lassen,  grob vergleichen und per copy&paste in den set Befehl übernehmen.
Anschliessend (möglicherweise mit etwas Verzögerung) sollte der Kontakt bei "get identityDetails" als "TRUSTED_VERIFIED" angezeigt werden.
|}
|}



Aktuelle Version vom 8. Juni 2024, 10:30 Uhr

Signalbot
Zweck / Funktion
Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messenger Signal
Allgemein
Typ Gerätemodul
Details
Dokumentation EN / DE
Thema
Support (Forum) Unterstützende Dienste
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.

Aktuell unterstützte Funktionen aus FHEM:

  • Senden und Empfangen von Nachrichten an Gruppen oder Einzelempfänger
  • Versenden von einem oder mehreren Attachments (Bilder) sowie Plots von SVG und DOIF
  • 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
  • Authentifizierte Befehle an FHEM senden (commandref/GoogleAuth) mit Favoriten
  • Blockieren von Kontakten und Gruppen
  • Verwalten und Betreten/Verlassen von Gruppen
  • Registrierung von neuen Nummern inklusive Hilfestellung für Captchas
  • Linken von bestehenden Accounts zu FHEM

Die Installation von signal-cli ist aktuell je nach Linux Kenntnissen durchaus anspruchsvoll. Daher gibt es ein Installationsscript welches 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.
  • Die Möglichkeit von SVG oder DOIF Plots zu versenden (mit & wie bei anderen Anhängen, Details in den Beispielen)
  • Wurde mit und für die aktuelle Version von signal-cli entwickelt, die auch die neuen "V2" Gruppen unterstützt, ebenso wird die neuste Version vom Perl Modul Protocol::DBus (aktuell 0.22) benötigt
  • Wird aktiv (Januar 2024) gewartet (letztes Update für SiSi auf github ist von August 2018)

"set" 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 für muss für fhem lesbar und absolut oder relativ zum fhem home sein) oder Stream einer Bilddatei (z.B.)SVG
  • Text: Die eigentlich Textnachricht, kann Leerzeichen und Umbrüche (mit "\n" oder \0x0a) 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')})

Ein paar Beispiele

 send @+498514711 Hallo Signal
 send #FHEM &/tmp/foto.jpg                             Ein Bild schicken
 send "@Mein Freund"                                   Leerzeichen durch Anführungszeichen um den ganzen Teilbefehl
 send @Joerg #FHEM #Familie                            Jeder Empfänger, jede Gruppe und Attachments können mehrfach vorkommen
 send "@({my $var=\"Joerg\";; return $var;;})"         Perl Code mit Leerzeichen ausführen
 send @(define dummy1 dummy)                           FHEM Befehl ausführen, wird aber nicht gesendet, da kein gültiger Empfänger zurück geliefert wird
 send @Joerg &({plotAsPng(\'SVG_Aussentemperatur\')})  Einen FHEM SVG Plot verschicken oder
 send @Joerg "&({plotAsPng('SVG_Aussentemperatur')})"  so - oder
 send @Joerg &SVG_Aussentemperatur                     so - oder
 send @Joerg "&SVG_Aussentemperatur,day,-1"            SVG Plot vom voherigen Tag
 send @Joerg &DI_uitable                               Sende erstes Widget aus einem DOIF mit definiertem uiTable
 send @Joerg "&DI_uitable,dev=outtemp,state"           Sende erstes Widget dass Werte aus der Device "outtemp" verwendet aus definiertem uiState 
 send @Joerg Mehrzeilige Ausgabe:\nNeue Zeile
 send @Joerg Umlaute öäü und Emojis 🙃😆🤗🤑🤪 sowie 𝐅𝐨𝐫𝐦𝐚𝐭𝐢𝐞𝐫𝐮𝐧𝐠𝐞𝐧 direkt senden oder
 send @Joerg <b>Fetter</b> Text und Emojis :) :smile: - siehe get helpUnicode für Details
 send @Joerg Die Aussentemperatur ist [out_temp:temperature] Grad

Tipp zu den Formatierungen: Auf z.B. https://yaytext.com/ kann man sich seine UTF8 Kodierungen erstellen und nach FHEM per copy&paste einfügen. Vorrausetzung dürfte sein, dass die "locale" des Systems auf UTF8 eingestellt ist

Hinweis: Signalbot bietet in den Device Details eine "send message" Zeile um bequem Nachrichten zu versenden. Hier gibt es jedoch durch das Webinterface einige Einschränkungen, z.B. in der Verwendung von Anführungszeichen. Für komplexere Nachrichten, daher möglichst "set send" verwenden.

Details zum Versenden von Plots

Seit Signalbot V3.5 wird eine vereinfachte Form der Versendung von SVG Plots und sogar von DOIF uiTable Widgets unterstützt (siehe DOIF/uiTable Schnelleinstieg). Entspricht der mit "&" übergebene Anhang einem FHEM Device, und ist dies vom Typ SVG oder DOIF, wird dies besonders behandelt.

Für SVG wird die Funktion "plotAsPng" dann intern aufgerufen. Es können dabei mit Komma getrennt noch der "Zoom" und das "Offset" angegeben werden, als "&SVG_Device,Zoom,Offset". Es wird empfohlen den Term in Anführungszeichen zu setzen, das z.B. DOIF die Kommas sonst als FHEM Befehlstrenner interpretiert. Zoom ändert nicht die Größe! Diese bitte ggf. im SVG Device anpassen.

Erlaubte Werte für Zoom: hour, qday, day, week, month, year, 10years, 20years

Offset dürfte üblicherweise eine negative Zahl sein, und gibt an wie oft man zurückblättert (Zoom gibt dabei die Einheit an).

Die Unterstützung der DOIF Widgets verwendet einige Internas von DOIF und daher kann die Kompatibilität mit zukünftigen DOIF Versionen leider nicht garantiert werden. Falls es nach einem DOIF update nicht mehr funktioniert, bitte in Forum posten. Widgets werden primär aus dem Attribut uiTable genommen, ist dies nicht vorhanden, oder wird der Parameter "state" angeben, schaut Signalbot auch in uiState nach. Eine spezielle Fehlerbehandlung gibt es derzeit nicht, sondern es kommt nur die Meldung, dass die Datei nicht gefunden wurde.

Syntax: "&DI_device,param1=wert1,param2=wert2" - die Verwendung von Anführungszeichen ist bei der Verwendung innerhalb eines DOIF nötig, das die Kommas sonst als Befehlstrenner interpretiert werden.

Mögliche Parameter:

  • id : Sequentielle Nummer des Widgets welches angezeigt werden soll. Dabei zählen auch seperate Beschriftungen. "id=" kann auch weggelassen werden und nur die Zahl angegeben werden. "id" hat Vorrang vor "dev" oder "val"
  • dev : Identifiziert das Widget über das FHEM Device aus welchem das Widget seine Daten holt. Ist dies nicht eindeutig, wird das Erste in der Liste verwendet - kann mit "val" kombiniert werden
  • val : dentifiziert das Widget über das FHEM Reading aus welchem das Widget seine Daten holt. Ist dies nicht eindeutig, wird das Erste in der Liste verwendet - kann mit "dev" kombiniert werden
  • zoom: Zoomfaktor bei der SVG->PNG Umwandlung. Dies ändert nicht die Größe des Bildes so dass ggf. Teile abgeschnitten werden.
  • sizex / sizey: Ändert die Größe des Bildes, aber nicht des Widgets. Es sollten also üblicherweise zoom, sizex und sizey kombiniert werden bis das Ergebnis passt oder die Größe gleich im DOIF Widget angepasst werden.
  • state : (ohne =) Hole die Widget Definition nicht aus uiTable sondern aus uiState

Achtung: Es gibt einen bekannten Fehler, dass die SVG library die Halbring-Darstellung in der uiTable card nicht verdaut und diese daher nicht verwendet werden kann

setContact <Number> <Contactname>

Definiert einen Kontakteintrag im internen Adressbuch. Es kann beim send Befehl dann der ContactName statt der Nummer verwendet 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.

createGroup <Groupname> [&<path to picture>]

Erzeugt eine neue Signalgruppe und versieht diese (optional) mit einem Gruppenbild.

updateGroup <Groupname> [<new Groupname>] [&<path to picture>]

Aktualisiert den Namen und/oder das Gruppenbild einer Gruppe.

invite <Groupname> <Contact1> [<Contact2>...]

Lädt einen oder mehrere Kontakte (per Namen oder Nummer) in eine bestehende Gruppe ein.

joinGroup <group link>

Einer bestehenden Gruppe beitreten. Dazu ist eine Einladung über einen "group link" nötig, der das Format https://signal.group/ https://signal.group/.... hat. Der einfachste Weg hierzu ist es, wenn aus der Signal App die Funktion "group link" verwendet wird und der Link dann per Signal an den FHEM User gesendet wird. Sofern das autoJoin Attribut gesetzt ist, wird dieser erkannt und FHEM tritt der Gruppe automatisch bei.

reply <message>

Wie "send", nur kann der Empfänger weggelassen werden - stattdessen wird die Nachricht an den Absender der zuletzt empfangenen Nachricht gesendet

trust <Contact|"all">

Setzt den entsprechenden Kontakt - oder mit "all" alle bekannten Kontakte auf "TRUSTED_UNVERIFIED". Dies ist manchmal nötig um von diesem Kontakt problemlos Nachrichten zu empfangen. Der Kontakt ist damit nicht vollständig verifiziert - dazu gibt es "trustVerified". Details über den Status eines Kontakts gibt es per "get identityDetails"

Die Liste ist mit Kontakten vorbefüllt, die noch "UNTRUSTED" sind - steht dort nur "all" sind also alle bekannten Kontakte mindestens "TRUSTED_UNVERIFIED". Sofern die Liste der Kontakte länger als 20 ist, ist die Nummer allerdings in ein Textfeld einzugeben, da das Dropdown sonst zu lang werden würde.

trustVerified <Contact> <SafetyNumber>

Validiert einen Kontakt als "TRUSTED_VERIFIED". Die SafetyNumber sollte üblicherweise auf einem sicheren Weg vom jeweiligen Kontakt übermittelt werden (z.B. vom persönlich vom Display abtippen oder über einen verifizierten Kommunikationskanal senden). Die Nummer ist aber symmetrisch (also für jedes Sender und Empfänger Paar gleich) und wird mit "get identityDetails" angezeigt und kann dort verglichen und dann einfach mit copy&paste übernommen werden. Kontakte denen voll vertraut wird, können via Signal Kommandos an FHEM senden, sofern authTrusted=yes gesetzt ist.

quitGroup <Groupname>

Aus einer Gruppe austreten. Die Gruppe wird dabei lediglich auf "inaktiv" gesetzt und ist mit get groups weiterhin als solche sichtbar. Eine Möglichkeit die Gruppe komplett aus dem Profil zu löschen besteht aktuell nicht.

block #<Groupname>|<Contact>

Blockiert eine Gruppe oder einen Kontakt (per Namen oder Nummer) serverseitig. Signalbot bekommt dann keine Nachrichten dieser Absender mehr (im Gegensatz zu allowedPeer bei der FHEM die Nachrichten noch bekommt, diese aber ignoriert.)

unblock #<Groupname>|<Contact>

Hebt die Blockierung wieder auf.

updateProfile <name> [&<Avatar picture>]

Setzt den Namen des Anwenders und optional ein Avatar Bild.

"set" Sonderfunktionen zur Registrierung

signalAccount <Telefonnummer>

Setzt eine bereits registrierte oder gelinkte Telefonnummer aktiv. Die bekannten Nummern werden als Pulldown zur Verfügung gestellt. Falls eine Nummer fehlen sollte, kann diese mit "set reinit" aktualisiert werden.

Ist nur eine Telefonnummer registriert, wird diese automatisch verwendet.

Wenn mehrere Nummern gleichzeitig verwendet werden sollen, braucht jede Nummer eine eigenen Instanz des Moduls.

register <Telefonnummer>

Eine neue Nummer für Signal registrieren. Die Telefonnummer muss in Internationaler Schreibweise (+49.....) angegeben werden.

Signalbot führt den Anwender in einer Art Wizard (Detailtexte auf der Modulseite) durch den Registrierungsprozess. Der erste Schritt ist, eine Nummer festzulegen. Üblicherweise ist das eine Festnetznummer, was die normale Verwendung der Nummer nicht beinträchtigt.

Achtung: Hier nicht die Handynummer eines Smartphones verwenden auf dem Signal schon installiert ist. Das Handy würde dadurch von Signal abgemeldet. Dazu kann "link" verwendet werden.

Wichtig: Im Laufe der Registrierung wird eine Verifikationsnummer übermittelt, normalerweise per SMS. Für Festnetznummern sollte man das aber üblicherweise auf Sprachanruf umstellen. Dazu das Attribut "registerMethod" auf "Voice" umstellen.

Die Registrierung wird meistens durch ein Captcha geschützt. Details dazu weiter unten.

captcha <signalcaptcha://.......>

Setzen des Captcha String im Rahmen der Registrierung. Details dazu, wie man den bekommt und wie der Prozess teilweise automatisiert werden kann weiter unten

verify <Verifizierungscode>

Setzen des Codes, den man im Rahmen der Registrierung per SMS oder Sprachanruf übermittelt bekommen hat.

Dies ist der letzte Schritt der Registrierung. Danach ist Signalbot einsatzbereit.

link <Name>

Zeigt einen QR Code an, den man mit der Signal App auf dem Smartphone scannen kann um FHEM als "Mitbenutzer" zu registrieren. FHEM erhält dann alle Nachrichten und gesendete Nachrichten haben den Absender des Telefons. Dies ist ein einfacher und schneller Weg um Signalbot auszuprobieren, sollte aber nicht für die produktive Benutzung verwendet werden, um unerwünschte Nebeneffekte zu vermeiden. Da FHEM nicht benachrichtigt wird, wenn der "link" zustande gekomme ist, muss danach manuell ein "set reinit" durchgeführt werden.

Der optionale Name (wenn leer wird "FHEM" verwendet) dient zur Identifizierung.

Die angezeigte URI kann mittels "addDevice" auch dafür verwendet werden zwei FHEM Instanzen miteinander zu verküpfen, welches auf der Hauptinstanz ausgeführt wird.

addDevice <device URI>

Fügt eine andere Instanz als "Mitbenutzer" hinzu. Die URI wird mit "set link" auf der anderen (nicht registrierten) FHEM Instanz erzeugt.

Dabei ist zu beachten, dass alle Nachrichten/Befehle an beide Instanzen gehen, was bei entsprechenden Triggern zu beachten ist. Ansätze dazu sind mit "allowedPeer" auf unterschiedliche Sender zu reagieren, unterschiedliche cmdKeyWord's zu setzen etc.

removeDevice <deviceID>

Entfernt einen Mitbenutzer anhand seiner deviceID. Diese kann mit "get devices" abgefragt werden. Wenn nur Mitbenutzer verlinkt ist, ist da üblicherweise "2" da "1" dem Hauptbenutzer zugeordnet wird.

"get" Funktionen im Detail

contacts all|nonblocked

Öffnet ein Fenster mit allen bekannten Kontakten mit Telefonnummer und Kontaktname sowie deren "blocked" Status. Mit dem Parameter "nonblocked" werden geblockte Kontakte ausgeblendet. Als Name wird primär der selbstdefinierte Kontaktname angezeigt. Sofern keiner definiert ist, wird der durch den Kontakt selbst definierte Profilname angezeigt.

chat <Contact|Group>

Signalbot speichert eine kurze Chat Historie per Kontakt oder Gruppe die hiermit abgerufen wird. Die Gruppen sind aktuell mit "+" statt "#" gekennzeichnet, da es mit dem "#" Zeichen Probleme in der Implementierung gab.

Die Historie wird nicht abgespeichert, ist also nach einem Neustart wieder weg und beschränkt sich auf 20 Zeilen.

groups all|active|nonblocked

Öffnet ein Fenster mit allen bekannten Gruppen. Es wird der Gruppenname, der "Active" Status (ist FHEM Mitglied der Gruppe), der "Blocked" Status sowie die Liste der anderen Gruppenmitglieder angezeigt. Mit dem Parameter "active" wird die Liste auf Gruppen beschränkt, in denen FHEM Mitglied ist, mit "nonblocked" werden zusätzlich noch geblockte Gruppen ausgeblendet.

accounts

Zeigt alle aktuell in signal-cli registierten Telefonnummern an, die mit "set signalAccount" verwendet werden können.

devices

Zeigt alle verlinkten Mitbenutzer an. Üblicherweise hat dies nur einen Eintrag (den Hauptbenutzer = aktuelle Instanz). Die ID Nummer können mit "removeDevice" verwendet werden um Mitbenutzer zu entfernen.

favorites

Listet die definierten Favoriten im Attribut "favorites" (siehe unten) in tabellarischer Form auf. Nützlich um zu prüfen ob das Attribut korrekt befüllt ist.

helpUnicode

Zeigt alle unterstützten Tags zur Formattierung von Nachrichten mittels HTML oder Markdown Tags.

Achtung: Die Funktion muss über dass Attribut formatting aktiviert werden.

identityDetails <Contact>

Zeigt Systemdetails zu einem Kontakt an. Neben dem vollen Namen, dem Trust Level (UNTRUSTED,TRUSTED_UNVERIFIED oder TRUSTED_VERIFIED), die SafetyNumer die mit "set trustVerified" verwendet werden kann um den TRUSTED_VERIFIED Status zu setzen, wann der Kontakt zu signal-cli hinzugefügt wurde sowie einen QR-Code der mit der Signal App gescannt werden kann um umgekehrt TRUSTED_VERIFIED für FHEM auf dem Telefon zu setzen.

Attribute im Detail

authTimeout

Gibt bei Verwendung des GoogleAuth device die Dauer in Sekunden an, die ein Nutzer authentifiziert bleibt. Siehe commandKeyword für mehr Infos.

authDev

Name des genutzten GoogleAuth device. Dies wird üblicherweise automatisch gesetzt, sofern bereits ein GoogleAuth device im System definiert ist, sobald das authTimeout gesetzt wird.

authTrusted

Falls auf "yes" gesetzt, dürfen Kontakte die den Vertrauensstatus "TRUSTED_VERIFIED" haben auch ohne GoogleAuth Kommandos an FHEM senden. Da Signal z.B. mit diesem Mechanismus vor Accountübernahme, Handywechsel etc. schützt, ist die Identität des Kontakts zweifelsfrei sichergestellt und die umständliche Eingabe eines Codes von GoogleAuth kann entfallen.

autoJoin 0|1

Falls auf 1 gesetzt, reagiert FHEM automatisch auf Einladungslinks (siehe joinGroup) und tritt der Gruppe bei

cmdKeyword

Eine Zeichenkette aus einem oder mehreren Zeichen, die am Anfang einer Nachricht stehen kann, damit FHEM die restliche Nachricht ungefiltert als Kommando ausführt. Die Funktion ist über GoogleAuth geschützt, d.h. ein Benutzer muss sich erst mit einem gültigen GoogleAuth Token legitimieren und bleibt entsprechend des authTimeout Attributs für gewisse Zeit authorisiert.

Beispiel:

Man setzt cmdKeyword auf "=" , dann kann man "=123456 set lamp off" senden. Im weiteren Verlauf reicht "=set lamp on" solange bis der Timeout abgelaufen ist.

Zur Authorisierung muss nicht zwingend gleich ein Befehl mitgesendet werden. Sofern allowedPeer gesetzt ist, muss der Absender zusätzlich in dieser Liste stehen.

defaultPeer

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

allowedPeer

Komma getrennte Liste von Gruppen, Kontaktnamen oder Nummern auf die Signalbot reagieren soll (also bei empfangenen Nachrichten Readings aktualisiert). Ist dieses Attribut nicht gesetzt, reagiert Signalbot auf alle Nachrichten.

babblePeer

Komma getrennte Liste von Gruppen, Kontaktnamen oder Nummern auf die Signalbot reagieren soll indem es die Nachricht an das über babbleDev (nicht zu verwechseln mit babbleDevice) definierte Babble Modul schickt. Die Nachrichten werden zuerst (beschränkt auf allowedPeer) normal verarbeitet (also Readings aktualisiert) und nur nach Babble gesendet wenn diese Attribut gesetzt ist.

Der Absender der Nachricht (Gruppe hat Prio über individuellem Absender) wird Babble als $PARM0 übergeben. Dazu in Babble noch das Attribut helpFunc wie folgt setzen

{fhem("set SignalBot send \@$PARM0 $HELP")}

Sollen die rivescript Spracherweiterungen genutzt werden muss außerdem "noChatbot" auf 0 stehen.

Nach dem selben Prinzip können in der Babble Definition auch Antworten spezfisch für Devices angelegt werden, z.B. als Aktion für out-temp -> Temperatur -> draußen -> sagen -> Status:

set SignalBot send @$PARM0 Die Temperatur draußen ist [out_temp:temperature] Grad

Womit die Frage (ohne Fragezeichen!) "Wie ist die Temperatur draußen" entsprechend quittiert wird.

babbleDev

Name des definierten Babble Device.Wird beim Setzen vom babblePeer automatisch mit der ersten "Babble" Device gefüllt sofern vorhanden.

babbleExclude

Regulärer Ausdruck auf den Nachrichtentext um bestimmte Nachrichten von der Weiterleitung zu Babble auszuschließen (ein Event wird trotzdem generiert und kann mit Notify, DOIF etc. verarbeitet werden).

registerMethod <SMS|Voice>

Stellt die Registrierungsmethode (Rückmeldung des Verifizierungscodes) auf SMS oder Sprachanruf um.

cmdFavorites

Definiert eine Zeichensequenz die bei remote Befehlen (siehe cmdKeyword) als Favorit interpretiert wird. Details siehe unter favorites. Da Favoriten vor FHEM Befehlen ausgewertet werden, sollte z.B. "set" nicht verwendet werden.

formatting <none|html|markdown|both>

Aktiviert die Ersetzung von html-ähnlichen Formatierungen (z.B. <b>bold text</b>) und/oder Markdown (z.B. __italic text__) um diese direkt in ASCII angeben zu können, anstatt nur per copy&paste.

Die komplette Liste von Tags/Ersetzungen kann über die get helpUnicode Funktion direkt im Model angezeigt werden.

favorites <[alias1]><-><command1>;<[alias2]><-><command2>;....

Definiert Favoriten um remote Befehle (siehe cmdKeyword) abzukürzen.

Einträge werden durch Semikolon getrennt und automatisch durchnummeriert.

Optional kann in eckigen Klammern "[]" ein alias angebenben werden, sowie ebenfalls optional dem Befehle ein Minuszeichen "-" vorangestellt werden, womit für diesen Befehl keine vorherige GoogleAuth Authentifizierung zu erfolgen hat.

Wichtig: Favoriten funktionieren nur wenn cmdKeyword, cmdFavorites, authTimeout, authDev und favorites gesetzt sind.

Beispiele (angenommen cmdKeyword="/" , cmdFavorites="fav", favorites="set lamp on;[off]set lamp off;[hi]-set talk say Jemand zuhause"):

Befehl Effekt
/fav 1 Fehler weil nicht authentifiziert
/fav 3 "set talk" Befehl wird ausgeführt, da "-" Befehle ohne Authentifizierung funktionieren
/fav hi "set talk" Befehl wird ausgeführt
/123456 GoogleAuth Token setzen um remote Befehle freizuschalten
/fav 1 "set lamp on" wird ausgeführt
/fav off "set lamp off" wird ausgeführt
/fav Liste all Favoriten mit IDs wird ausgegeben

Readings im Detail

account Aktuell verwendete Telefonnummer (nur verfügbar wenn signal-cli 0.9.0 ohne -u Parameter gestartet wurde)
joinedGroups Liste der beigetretenen Gruppen getrennt mit Leerzeichen
lastError Text der letzten Fehlermeldung. Bitte unbedingt den Timestamp beachten. Das Reading wird bei erfolgreichen Aktionen nicht zurückgesetzt und enthält ggf. sehr alte Fehlermeldungen.
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
msgAuth Ist auf 1 gesetzt wenn der Absender der aktuellen Nachricht (also zum Zeitpunkt zu dem z.B. ein Notify/DOIF die Nachricht auswertet) per GoogleAuth authentifiziert war.
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
VERSION Internal Reading die die aktuelle Version von Signalbot, signal-cli und Dbus angibt - vor Support Anfragen bitte erst im Forum prüfen ob die aktuellste Version verwendet wird und ggf. updaten.

Installation

Zur Installation steht das Script "signal_install.sh" zur Verfügung, welches aber nicht zwangsweise in jeder Umgebung funktioniert. Daher erst einmal ein paar Referenzen zur manuellen Installation von signal-cli:

Vorbereitung:

Das Script "signal_install.sh" aus der Detailseite des Moduls oder vom FHEM SVN runterladen und ins Verzeichnis eines beliebigen "sudo"-fähigen Users kopieren.

Das Script hat mehrere Optionen um Teilfunktionen direkt auszuführen, diese sind:

Argument Bedeutung
system System für die signal-cli Installation vorbereiten. Es werden per "apt install" fehlende Pakete installiert und Verzeichnisse erstellt.

Muss mindestens einmal erfolgreich gelaufen sein, damit die restliche Installation funktioniert

install Installiert signal-cli als System Service. Automatischer Download, Installation und Konfiguration (dbus, systemd)
test Versendet eine Testnachricht auf zwei Arten - direkt mit dem Client (klappt das, ist die Grundregistrierung schon mal erfolgreich) und über Dbus (dann ist auch der System Service korrekt eingerichtet)
remove Löscht alle durch "install" installierten Verzeichnisse und Dateien (aber nicht die Pakete die durch "system" installiert wurden)
start Starten des singal service über systemd bzw. im Container des Dbus daemon and signal-cli Daemon
backup Erstellt ein Archiv aller relevanten Scripts und Einstellungen (z.B. für einen System Umzug) in der Datei signal-backup.tar.gz
restore Schreibt die Archive Datei signal-backup.tar.gz ins System zurück

Im Normalfall kann das script einfach unter root Rechten, also mit

sudo -E ./signal_install.sh

aufgerufen werden (wenn das Script per Download geholt wurde, muss es vorher noch mit "chmod a+x signal_install.sh" ausführbar gemacht werden). Wenn kein Argument übergeben wird, dann wird automatisch der Ablauf system -> install -> test durchlaufen.

Wenn Betriebssystem oder CPU Architektur nicht unterstützt werden, gibt es eine Warnung bzw. das Script bricht ab.

Hinweis: Es prüft außerdem ab, ob es im Container läuft. Dieser Modus ist nur dafür gedacht, wenn mein FHEM/Signal Container Script verwendet wurde. In anderen Container Umgebungen wird es üblicherweise nicht funktionieren. Details dazu weiter unten.

Dann Modul per "define <name> Signalbot" definieren.

Registrierung

Die Registrierung wird ab Version 3.0 nicht mehr im Script sondern in FHEM selbst geführt durchgeführt.

Hinweis: Eine Nummer kann immer nur einmal registriert sein. Eine bereits bestehende Registrierung (Smartphone) wird dabei aufgehoben. Daher entweder eine Festnetznummer verwenden mit der Option "link" FHEM als Zweitbenutzer zu einer bestehenden Nummer hinzugefügen. Dies ist zum Testen ok, aber produktiv ist davon abzuraten, da FHEM dann alle Mitteilungen bekommt die man am Handy auch kriegt, was zu unerwarteten Nebeneffekten führen kann.

Die Registrierung erfolgt mit "set register <nummer>" (Telefonnummer in internationaler Schreibweise mit +49....).

Nach erfolgter Registrierung bekommt man je nach Wert des Attributs "registerMethod" eine SMS oder einen Sprachanruf mit einer Verifikationsnummer.

Signal versucht sich gegen unberechtigte Nutzung des Service (man könnte ja damit quasi SMS/Telefonterror betreiben) zu schützen. Nach gewissen Kriterien (soweit bekannt z.B. Registrierung aus einer VM oder über VPN) wird daher ein Captcha verlangt.

FHEM führt hierbei durch den Prozess mit Hilfestellungen

Ablauf:

  1. Captcha Seite von Signal aufrufen. Link ist auch direkt in FHEM verfügbar
  2. Nach erfolgreichem Lösen des Captchas erscheint ein Link "Signal öffnen" bzw. unter Windows besteht eine Automatisierungsoption (siehe unten)
  3. Üblicherweiser (Browserspezifisch) kann hier mit Rechtsklick und "Adresse des Links kopieren" das "signalcaptcha" kopiert werden
  4. Diesen String dann im "set captcha" Befehl eintragen und dann sollte die Registrierung weitergehen (SMS/Anruf)
    • SMS: Hier sollte relativ zeitnah eine SMS mit einem 6-stelligen Code übermittelt werden
    • Voice: Die Registrierung per Sprachanruf ist mit einigen Hürden versehen. Man muss erst mit SMS registrieren, 1 Minute warten, dann mit Voice. Ab Signalbot V3.19 wird dieser Vorgang automatisiert. Dauert aber durch die zwingende Wartezeit von 1 Minute ein wenig.

Captcha "Automatisierung":

Am einfachsten ist die Registrierung wenn sich von Windows aus mit FHEM verbindet. Hier stellt Signalbot ein Windows Registry File (signalcaptcha.reg) zum Download zur Verfügung. Dieses einfach runterladen und per Doppelklick in die Registry eintragen.

Wenn jetzt die Signal Captcha Seite besucht wird, wird nach Bestätigung ein Powershell Script welches einfach wieder FHEM mit der entsprechenden "set captcha" Befehl automatisch ausführt.

Für Linux habe ich aktuell nur eine Lösung für Firefox. Hier die signalcaptcha.desktop runterladen und nach ~/.local/share/applications/signalcaptcha.desktop kopieren und mit xdg-mime default signalcaptcha.desktop x-scheme-handler/signalcaptcha (alles mit dem Desktop User) aktivieren. Dann sollte ebenfalls automatisch FHEM aufgerufen werden.

Wichtig: Wenn csrf-Tokens nicht abgeschaltet sind, werden diese bei jedem FHEM Neustart neu erzeugt, womit man auch neue .reg/.desktop Dateien benötigt (set reinit, neuer Download)

Verifizierung

Zuletzt wird mit "set verify" der Verifizierungscode eingetragen und die Registrierung ist damit abgeschlossen.

Bestehende Nummer verlinken

Alternativ kann man auch eine bestehende Nummer verlinken. Dazu "set link" aufrufen. Es wird jetzt ein QR-Code auf dem Bildschirm angezeigt. In der Signal App dann auf Settings->Linked Devices gehen und mit "+" den QR-Code abfotografieren.

Bitte beachten, dass bei verlinkten Devices immer alle Devices (also auch das Smartphone) Nachrichten bekommen. Bei reinem Sendebetrieb dürfte das weniger stören, soll aber auch auf Befehle reagiert werden, dann ist das eventuell verwirrend.

Einrichtung des Moduls

Siehe Forenthema Neues Modul: Signalbot.

Nachdem alles sauber eingerichtet ist und das Modul im FHEM Directory abgelegt wurde, entweder ein "reload 50_Signalbot" oder besser ein "shutdown restart" von FHEM machen.

Das Modul dann einfach mit

define <name> Signalbot

definiert.

Umstieg von SiSi

Da SiSi eine inzwischen sehr alte signal-cli Version verwendet, die sehr wahrscheinlich nicht mehr voll abwärtskompatibel ist, wird von einer einfachen Migration abgeraten.

Die Installation und Neuregistrierung der Nummer ist inzwischen soweit vereinfacht worden, dass diese Vorgehensweise weniger aufwändig ist.

Ohne Garantie, dass dies mit der aktuellen signal-cli/Signalbot Version noch funktioniert hier trotzdem die potentielle Migration:

Signalbot allerdings eine andere Dbus Implementierung (Protocol::DBus), diese muss erst installiert werden:

cpan install -f Protocol::DBus

Sofern nach dem SiSi Wiki vorgegangen wurde, dann sind folgende Anpassungen im Script notwendig:

SIGNALPATH=/opt/fhem
SIGNALUSER=fhem
SIGNALVAR=/opt/fhem/.local/share

Das Verzeichnis /opt/fhem/signal-cli kann gelöscht werden.

Wenn mein Installationsschema übernommen werden soll, dann

sudo mv /opt/fhem/.local/share/signal-cli /var/lib

Jetzt kann das Script einfach wie oben beschrieben gestartet werden.

Umzug auf ein neues System

Dazu einfach das Script mit dem Argument "backup" starten. Die alte Konfiguration wird dabei im Home Verzeichnis des aktuellen Benutzers als ~/signal-backup.tar.gz gesichert.

auf dem neuen System dann diese Datei wieder ins Home und entsprechend das Script mit "restore" laufen lassen.

Eigene native Library übersetzen

Signal-cli ist zwar überwiegend in Java geschrieben, hat aber leider eine binäre Library die zwingend benötigt wird. Ohne diese startet der Service nicht.

Der Installler lädt automatisch die korrekte Library für unterstützte Architekturen und ersetzt die am64/glibc-2.31 die von signal-cli standardmäßig mitgeliefert wird. Unterstützt werden aktuell:

  • Raspberry (armv7l) für Buster (glibc2.28) und Bullseye (glibc2.31)
  • Raspberry 64-bit (aarch64) für glibc2.28 (ungetestet, sollte für Buster und Bullseye funktionieren)
  • AMD/Intel 64-bit (amd64) für glibc2.28 und glibc2.31 (Ubuntu 18,20,22, Debian 10,11 u.a.)

Es gibt mehrere github Projekte um signal-cli die auch fertig übersetzte libsignal_jni.so im Angebot haben (einfach mal suchen). Man kann sich die Library aber auch selbst übersetzen.

Ich gehe dabei davon aus, dass eine (wenn auch inkompatible) Installation von signal-cli bereits erfolgt ist und z.B. alle Java libraries an Ort und Stelle sind.

Es werden eine Reihe von Programmen benötigt. Diese Liste ist möglicherweise nicht vollständig, je nachdem wie eurer System konfiguriert ist:

sudo apt-install git build-essential clang cmake openjdk-17-jdk-headless
sudo curl https://sh.rustup.rs -sSf | sh

Es ist hier wichtig, dass die libsignal-client in der Version passt, daher in der signal-cli Installation checken

ls /opt/signal/lib/libsignal-client*

Und die Versionsnummer notieren (für signal-cli 0.11.3 ist das 0.20.0) Jetzt entsprechend auschecken

git clone git@github.com:signalapp/libsignal-client.git
cd libsignal-client
git checkout v0.20.0
cd java
./build_jni.sh desktop

libsignal_jni.so aus target/release/ nach /opt/signal/lib kopieren Libraries in den Java .jar Files durch die selbst compilierten ersetzen:

cd /opt/signal/lib
sudo -u signal-cli zip -u signal-client-java-*.jar libsignal_jni.so

Dann Service neu starten

sudo service signal start

Wenn alles richtig funktioniert hat, sollte der Service jetzt laufen (syslog prüfen, oder ps -ef | grep signal-cli )

Installation im Docker Container

Um signal-cli in einem Docker Container zu installieren stellt sich die Schwierigkeit, dass man dort nicht so einfach Dienste per systemd starten kann und die Kommunikation zum System Dbus schwierig ist. Dies wird in durch die spezielle Docker Installation umgangen, indem der dbus-daemon dort eigens gestartet wird und signal-cli per script in den Hintergrund gestartet wird.

Unter Verwendung dieses Scripts wird eine komplette FHEM Basisinstallation per Docker erstellt und dort signal-cli eingerichtet.

Funktionsweise:

Das Script erstellt alle notwendigen Dateien in einem User Verzeichnis (default: $HOME/fhem) und installiert dort auch in "fhem-<version>" die aktuelle FHEM Version sowie ein Verzeichnis "signal" für die Registrierungsdaten. Diese sind somit persistent außerhalb des Containers und können auch von außen überschrieben werden.

Wer bereits eine Signal Registrierung einer normalen Installation hat, kann diese von /var/lib/signal-cli in dieses "signal" Verzeichnis kopieren, so das sie verwendet wird.

Das Script muss mit "sudo" ausgeführt werden und hat noch die Option "remove" alle Dockerdateien die es erzeugt auch wieder zu entfernen. FHEM bleibt dabei unangetastet.

Bei einer erneuten Erstellung des Containers (z.B. um package updates oder eine neue signal-cli Version einzuspielen) kann man wählen FHEM nicht neu zu installieren womit es danach genauso konfiguriert wieder gestartet wird.

Der Container wird basierend auf einem aktuellen Ubuntu Image erzeugt (aktuelle Ubuntu 20.04). Falls in FHEM Module verwendet werden, müssen oft weiteren Pakete (über apt, cpan oder npm) installiert werden. Im Installscript finden sich hier auskommentiert ein paar Hinweise wie für einige gängige Module (bzw. eben welche die ich verwende) die entsprechenden Abhängigkeiten mit eingebunden werden können.

Achtung: Das Ganze ist experimentell und für eine einmalige Installation/Start gebaut. Wenn fhem, signal-cli oder der dbus-daemon im Docker beendet werden, dann muss man diese evtl. selbst wieder nachstarten. Das kann man sicher noch einiges verbessern. Sinnvollerweise nimmt man die erzeugten Config Dateien und Scripte eher als Anregung für eine eigene Konfiguration. Verbesserungsvorschläge gerne auch im Forum.

Versenden von Nachrichten ohne FHEM

Falls jemand auch aus Shell Scripten heraus Signal Nachrichten versenden möchte, kann die FHEM signal-cli Installation am einfachsten über den "dbus-send" Befehl mitverwendet werden:

dbus-send --system --type=method_call --print-reply --dest=org.asamk.Signal /org/asamk/Signal/_xxxxxx org.asamk.Signal.sendMessage string:Hallo array:string: string:+49yyyy

/org/asamk/Signal/_xxxxxx entspricht hier der registrierten Nummer und steht in FHEM Signalbot im Status ("connected to ..."). Dabei wird das "+" in der Nummer durch "_" ersetzt.

Wichtig ist bei Dbus Nachrichten nicht nur der Name der Methode (sendMessage) sondern auch Typ und Reihenfolge der Parameter. Für sendMessage heisst das:

  1. Die eigentliche Nachricht als String
  2. Ein Array von Strings die Attachments enthalten (da man dies von der Kommandozeile eher nicht machen wird, erzeugt array:string hier einen leeren Parameter)
  3. Die Telefonnummer der Empfängers als String

Grundsätzlich kann man so alle Dbus Methoden von signal-cli ansteuern, welche unter https://github.com/AsamK/signal-cli/blob/master/man/signal-cli-dbus.5.adoc dokumentiert sind.

Einige Dinge sind aber nicht so komfortabel, z.B. kann man Gruppen nicht per Namen, sondern nur über einen langen base64-kodierten String ansteuern - hier übernimmst SignalBot eine benutzerfreundliche Übersetzung.

Eine weitere Alternative ist dann einfach einen FHEM Befehl abzusetzen - z.B. per telnet Kommando.

Alternativ geht es auch direkt über den signal-cli client. Dafür muss aber vorher der service beendet sein (Konflikt):

sudo service signal stop 
sudo -E -u signal-cli /opt/signal/bin/signal-cli -c /var/lib/signal-cli -u +49<registrierte Nummer> send -m "testmessage" +49<Empfänger>

Fernsteuerung und Authentifizierung

Signalbot ermöglicht es FHEM über Signal fernzusteuern und dies auch abzusichern.

Um die Fernsteuerung zu aktivieren muss zuerst über das Attribut "cmdKeyword" festgelegt werden, woran Signalbot erkennen soll, dass es sich um einen Befehl handelt. In dieser Dokumentation gehe ich jetzt davon aus das "/" als Keyword gesetzt ist. Das Keyword kann auch mehrere Zeichen lang sein.

Sendet man jetzt "/set lamp on" an Signalbot, so führt dieser das entsprechende set Kommando direkt aus.

Dies ist natürlich sicherheitstechnisch ein offenes Scheunentor und es gibt mehrere Methoden der Absicherung

Attribut allowedPeer

Dieses Attribut enthält eine Komma-getrennte Liste von Nummer, Kontakt- oder Gruppennamen welche als gültige Absender akzeptiert werden. Ist es nicht gesetzt kann jeder mit Signalbot kommunizieren und Kommandos senden oder Events triggern

GoogleAuth

Vorrausetzung ist, dass man in FHEM ein GoogleAuth Device angelegt hat und entsprechend auch die App auf dem Telefon. Näheres in der Commandref.

Über das Attribut "authDev" kann die GoogleAuth Device zugewiesen werden. Üblicherweise ist dies nicht erforderlich, da SignalBot dieses in System sucht und das Attribut automatisch setzt.

Um die Prüfung per GoogleAuth zu aktivieren wird das Attribut "authTimeout" (in Sekunden) gesetzt, welches definiert wie lange eine erfolgreiche Authentifierung gültig bleibt.

Wenn jetzt Befehle an FHEM gesendet werden, quittiert Signalbot diese mit "You are not authorized to execute commands". Zur Authentifizierung wird einfach die 6-stellige Nummer aus dem Google Authenticator mit vorangestelltem Keyword an FHEM gesendet, also z.B. "/123456"

Man erhält die Meldung, dass man nur für gewisse Zeit (authTimeout) authentifiziert ist und kann Kommandos senden.

Trust

Signal hat eine eigene Funktionalität um Kommunikationspartner zu überprüfen und Ihnen das Vertrauen auszusprechend. Siehe dazu "set trust" und "set trustVerified". Da die Authentifizierung per GoogleAuth auf Dauer lästig sein kann, besteht die Möglichkeit diese für verifizierte vertraute Nutzer zu umgehen. Dazu wird das Attribut "authTrusted" auf "yes" gesetzt. Nutzer denen nicht voll vertraut wird, müssen sich weiter authentifzieren.

Favoriten

Der Vollständigkeit halber sei hier noch erwähnt, dass man Befehlskürzel per Favoriten definieren kann. Details dazu in der Beschreibung der set Befehle und Attribute.

Per Attribut "cmdFavorite" wird festgelegt welches Keyword die Favoritenauswahl triggert. Das könnte z.B. auch "/" sein, so dass "// 1" den ersten Favoriten triggert. Dass Attribute "favorites" enhält dann die eigentliche Definition der Favoritenliste.

Troubleshooting / FAQ

Anmerkung: Ich gehe hier davon aus, dass die Installation mit den im Script voreingestellten Pfaden/Users durchgeführt wurde. Änderungen auf eigene Gefahr.

Bevor ich hier ein paar typische Probleme und Lösungen aus dem Foren Thread aufliste, bitte folgende Punkte sicherstellen:

  1. Ich verwende eine unterstütztes Betriebssystem (Raspbian oder Ubuntu) und CPU Architektur (armv7l oder x86)
  2. Ich habe das neuste Install Script aus https://svn.fhem.de/fhem/trunk/fhem/contrib/signal/ verwendet
  3. Ich habe vor der Installation nach besten Wissen und Gewissen Reste einer vorherigen Installation (z.B. auch für SiSi) entfernt (das Repository kann weggesichert werden um eine erneute Registrierung zu vermeiden und dann statt dem Registrierungsschritt in /var/lib/signal-cli kopiert werden
  4. Ich habe das Install Script gemäß Anleitung vollständig durchlaufen lassen und auf Fehlermeldungen geachtet

Wo finde ich Fehlermeldungen/Logfiles?

  • Beim Install Script direkt in der Console - achte auf die Bildschirmausgabe
  • Beim Install Script auch in /tmp/signal_install.log - ggf. wegsichern da es bei jedem Durchlauf wieder überschrieben wird.
  • Fehler beim Starten und Betrieb des signal-cli service (normale Installation) in /var/log/syslog
  • Fehler beim Betrieb in FHEM im normalen FHEM log (ggf. Signalbot mit verbose=5 definieren)
  • Im Container, sofern die Daemons mit dem Install Script gestartet wurden, schreiben ihr log in /var/log/dbus.log bzw. signal.log und die Fehlerausgabe in /var/log/dbus.err bzw. signal.err

Probleme bei normaler Installation

Fehler Lösungsansatz
In FHEM:

Error sending message:org.asamk.Signal.Error.Failure: org.whispersystems.signalservice.api.push.exceptions.NotFoundException: Not found

signal-cli läuft nicht.

Prüfe ggf. /var/log/syslog für weitere Fehlermeldungen.

Führe sudo service signal start aus.

signal-cli läuft nach reboot oder restart nicht, aber ein manueller Start ist erfolgreich.

sudo systemctl status dbus-org.asamk.Signal.service

meldet einen timeout

Möglicherweise dauert das Starten von signal-cli länger als der standard 90sec Timeout des systemd (langsames System, langsame SD-Karte bei Raspberry, viele gleichzeitiger Startprozesse bei Reboot).

Hier kann man in /etc/systemd/system/signal.service den Timeout erhöhen indem in der Sektion [Service] die Zeile

TimeoutSec=200

eingefügt wird.

Bei Starten von signal-cli:

OpenJDK Server VM warning: You have loaded library /tmp/resource17792002454964883349.so which might have disabled stack guard. The VM will try to fix the stack guard now.

It's highly recommended that you fix the library with 'execstack -c <libfile>', or link it with '-z noexecstack'.

oder

ERROR App - Missing required native library dependency: libsignal-client

Passiert üblicherweise auf dem Raspberry pi. Die Standard Distribution von signal-cli enthält eine x86 library libsignal_jni.so, die mit armv7l nicht kompatibel ist, welche im jar libsignal-client-*.jar enthalten sind. Das Install Script entfernt diese und ersetzt sie durch armv7l libraries die vom Signalbot Maintainer auf svn.fhem.de zur Verfügung gestellt werden.

Irgendwo auf dem System vorhandene alte Versionen können aber versehentlich erwischt werden und diese Fehler produzieren. Als ersten Schritt mit

sudo rm -rf /opt/signal

die alte Installation komplett löschen (enthält keine Konfigurationen) und vom Install Script neu erstellen lassen (einfach wie oben beschrieben starten).

Weitere Tests wenn der Fehler nicht behoben ist:

  1. Welche Library wird vom System verwendet: sudo ldconfig -v | grep libsignal_jni.so . Da die libraries in .jar files eingebettet sind, darf hier keine gefunden werden.
  2. Check gibt es noch irgendwo ein anderes jar sudo find / -name libsignal-client-*.jar 2>/dev/null Wenn ja, sicherstellen, dass diese nicht genommen wird (löschen, umbenennen)
Beim Start von signal-cli:

Fehler: Beim Laden der Klasse org.asamk.signal.Main ist ein LinkageError aufgetreten

java.lang.UnsupportedClassVersionError: org/asamk/signal/Main has been compiled by a more recent version of the Java Runtime (class file version 65.0), this version of the Java Runtime only recognizes class file versions up to xx.0

Signal-cli benötigt seit der Version 0.13+ eine vorhandene Java 21 Installation. Ältere Systeme haben von Haus aus aber nur Java 11 oder 17.

Das Install Script kann hier helfen und eine Binärdistribution von OpenJDK 21 installieren und setzt JAVA_HOME im Startup des Service üblicherweise auch entsprechend.

Wenn signal-cli allerdings in der Kommandozeile ausgeführt wird, ist darauf zu achten das JAVA_HOME=/opt/java gesetzt ist (bzw. auch die von euch gewählte Java 21 Distribution).

Ein häufiger Fehler ist auch beim sudo das "-E" zu vergessen, denn nur so wird JAVA_HOME beim sudo "durchgereicht".

Fehler beim Setzen des Captcha: "Incorrect captcha - e.g. needs to start with signalcaptcha://"
  1. Sicherstellen, dass das Captcha tatsächlich korrekt ist - am Besten die Automatisierung über die Windows Registry verwenden
  2. Alternativ kann die Registrierung auch in der Kommandozeile vorgenommen werden
sudo service signal stop 

cd /opt/signal/bin/ 

sudo -E -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 register --voice --captcha signalcaptcha://03AG.... 

sudo -E -u signal-cli ./signal-cli --config /var/lib/signal-cli -u +4912456 verify 12345

sudo service signal start
Fehler: Untrusted Identity for "+49xxxxxxx" beim Versenden von Nachrichten.

Dieses Fehlerbild ist zu erwarten, wenn ein bereits bestehender Kontakt sich erneut bei Signal angemeldet hat (z.B. Handywechsel) und sich der Sicherheitscode dadurch geändert hat.

Mit "set trust <Nummer>" das Vertrauen (unverified) zum Kontakt wieder herstellen.

Sollte das nicht reichen (Nachrichten kommen nicht an / werden nicht empfangen) siehe weiter unten "Ich kann Nachrichten ohne Fehler senden....."

Senden von Nachrichten schlägt fehl oder Nachrichten werden nicht versendet Zur Prüfung ob der Fehler in FHEM, der DBUS Konfiguration oder bei signal-cli liegt, sind im Kapitel "Versenden von Nachrichten ohne FHEM" Methoden beschrieben direkt mit Dbus oder von der Kommandozeile Nachrichten zu senden.

Sicherstellen, dass mit "updateProfile" ein Name für das aktuelle Profil angelegt ist, sonst werden Nachrichten möglicherweise nicht verschickt.

Signal-cli started nach "apt update/upgrade" unter Raspberry Bullseye oder Buster nicht mehr.

Fehlermeldungen z.B. wrong ELF class: ELFCLASS64 (Possible cause: can't load AARCH64 .so on a ARM platform)

oder

Fehler wenn signal-cli als service läuft im syslog:

Caused by: org.sqlite.NativeLibraryNotFoundException: No native library found for os.name=Linux, os.arch=aarch64, paths=[/org/sqlite/native/Linux/aarch64:/usr/java/packages/lib:/lib:/usr/lib]

Seit März 2023 stellt Raspian anscheinend den Kernel auf 64bit um, sofern es sich um einen neueren 64-bit fähigen Raspberry handelt. Mit dem Befehl "arch" wird dann "aarch64" statt "armv7l" ausgegeben.

Aktuell hilft hier nur wieder auf den 32-bit Kernel umzustellen.

Dazu am Ende der /boot/config.txt die Zeile

arm_64bit=0

einfügen. Das Mischmasch aus 64Bit Kernel und 32Bit libraries bringt den Java loader für native libraries durcheinander. Aktuell ist dazu keine andere Lösung bekannt.

Die Registrierung schlägt fehl , z.B. mit der Fehlermeldung "Rate limit exceeded"
  1. Ein paar Stunden warten und es dann nochmal probieren (bei Rate limit exceeded)
  2. Anderen Browser probieren - es gibt Berichte, dass Firefox nicht funktioniert - Chrome scheint hier die bessere Wahl zu sein
Ich kann Nachrichten ohne Fehler senden, diese kommen aber beim Empfänger nicht an.

Ich empfange keine Nachrichten, obwohl diese vom Sender korrekt abgeschickt wurden.

Möglicherweise liegt es daran, dass dem Kontakt nicht vertraut wird.

Am Handy in die Details des FHEM Kontakts gehen, Sicherheitsnummer anzeigen und als verifiziert markieren. In FHEM "set trustVerified" mit der Telefonnummer des Kontakts und dessen Sicherheitsnummer ausführen. Damit man die Sicherheitsnummer nicht abtippen muss, kann man diese auch mit "get identityDetails" anzeigen lassen,  grob vergleichen und per copy&paste in den set Befehl übernehmen. Anschliessend (möglicherweise mit etwas Verzögerung) sollte der Kontakt bei "get identityDetails" als "TRUSTED_VERIFIED" angezeigt werden.

Links